Package and Constant Conventions [and a little Java 101] (was: Re: [C2][VOTE - it is a new one] Sync C2.0 and C2.1 branches)

[Berin Loritsch <bl...@apache.org>]

"Piroumian, Konstantin" wrote:

> > Samples should never be packaged with the main jar.  They should be
> compiled
> > into the WEB-INF/classes/ directory.  Use the package name:
> >
> > org.apache.cocoon.sample
> >
> 
> Btw, should the actions be in the core? I noticed some action specific
> constants in the org.apache.cocoon.Constants (related to form validation).

We should probably clean that part up.

Cocooners,

We should probably come to a consensus as to where things belong.  Our
code conventions cover most issues, but here are a few more good
idioms that we should probably adopt:

1) If a Constant is ONLY used by one Component (i.e. Action, Generator, etc),
   that constant should be included inside the class that uses it.

2) If a Constant is used by all clients of a Work Interface, then that
   constant should be included inside the interface that requires its
   use.

3) If a Constant is not tied to an implementation OR an interface, then
   (and only then) should it be placed in the org.apache.cocoon.Constants
   interface.

4) All compiled code for samples should never be part of the Cocoon.jar,
   the classes should be compiled into the WEB-INF/classes directory of
   the samples webapp.  We should use the package naming convention of
   org.apache.cocoon.samples.{sampleName} where "{sampleName}" is replaced
   with the name of the sample you are creating.


Idioms 1-3 can be summarized in an approach I use that helps me write
maintainable and predictable code:

"Localize as much as possible".

I have another one that says, "Always use Explicit scoping".

Those two approaches minimize the number of Classes and Interfaces you
must import to get your implementation working, and assures you that
you are using the correct variable.

Examples of Explicit Scoping:

static variable:  ClassName.myStaticVariable;
static method:    ClassName.staticMethod();

class variable:   this.myClassVariable;
class method:     this.myClassMethod();

super variable:   super.superClassVariable;
super method:     super.superClassMethod();

local variable:   localVariable;


By using these common sense approaches, all your scope related bugs
go away.  There were a number of bugs in my company's proprietary
software that dealt with novice programmers and scoping related
issues.  Basically, they declared a class variable that they expected
to share for all the methods.  In the initialization code, they
declared and initialized a LOCAL instance of the variable with the
same name as the class variable.  The end result was that when
another method tried to use the class variable it didn't work.

Bad Example:

class Java101BadClass {
    private JComboBox myCombo;

    public Java101BadClass() {
        // Note the local variable and class variable
        // have the same name
        JComboBox myCombo = new JComboBox();

        // These methods are called on the local variable
        myCombo.addItem("This");
        myCombo.addItem("won't");
        myCombo.addItem("show");
    }

    public JComboBox getBadInstance() {
        // The class variable doesn't work, and the reason
        // for it isn't all that obvious
        return myCombo;
    }
}

Good Example:

class Java101GoodClass {
    private final JComboBox myCombo;

    public Java101GoodClass() {
        this.myCombo = new JComboBox();

        this.myCombo.addItem("This");
        this.myCombo.addItem("will");
        this.myCombo.addItem("show");
    }

    public JComboBox getBadInstance() {
        // The class variable works
        return this.myCombo;
    }
}

In the above example, even if you made the same mistake with
creating a local variable with the same name the code will
fail earlier and the cause would be much more obvious.  In
fact, some compilers might warn you that the variable may not
have been initialized (only works with final class variables)!

---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org