Coding Standards

[Johnathan Meehan]

Hi,

So, if a few of us are now writing code do you think we should go
about defining some sort of standard? I think it might be an idea to
get it done before the code base grows, and it would also be nice to
run clean-up before passing on patches without creating a difficult to
understand diff. :) I'm not talking about anything complicated as we
could just use the Java standard (as included with Eclipse) with minor
tweaks, which would be helpful when considering that we might also
need to make changes for Sonar and Hudson.

What do you think? To start things, a couple of minor suggestions to
consider:

- The Apache header. As the project's licence is Apache 2 I think we
might include the licence header to clearly identify source files
belonging directly to the project and under those terms.
- Javadoc. Require Javadoc for each type, method and class-level
variable and, unlike my submisson last night, try to make them
meaningful.
- Apply "final" as standard for variable declarations.
- Apply "this" as needed.
- Comments. Multi-line comments must use the /* */ format.
- Method sorting. Leave the original method order intact.
- Maxium line width. Don't impose this; leave to common sense.
- Since tags for changes to the public interfaces, and all newly
created types.

Only the Javadoc here would not be handled by clean-up in Eclipse -
not sure how other IDEs would operate.

[Nicholas Whitehead]

Not sure how many are using Eclipse, but here's a code template I whipped up that implements some of the headers Jonathan outlined.

//Nicholas

[Johnathan Meehan]

Great. I changed the licence text to be a comment rather than a Javadoc style comment; we can revert it of course, but I thought that was more in line with general usage. I also added a since tag to the type Javadoc. I know that was for discussion, but next along can just remove it. For overridding methods should we use "/** {inheritDoc} */" rather than just "/** ${tags} */"? How many times do you actually rewrite the docs? :)

I mucked around with the clean-up and code formatting options too, but there's a lot there so I will just mention that I put private fields and local variables to be marked as final, but left parameters alone so we don't need to copy for modification. Anyhow, add what you like, remove what you don't and twiddle with the rest and we'll see where we get to.

[Roger Schildmeijer]

Will take a look at the xml files during the weekend.

-----------

Some personal reflections about the proposed coding standard.

- License headers

Good idea.

- Javadoc

Im not sure I like the idea to document _everything_. Im more like a "document-only-if-needed"-guy

- Final

I like immutability for attributes (if possible). (would be nice if immutability was default for variables, params and fields, unfortunately it isn't). Insert final everywhere => more code :(

- this

Only insert 'this' when needed. (like ctor and setters). Otherwise omit.

- max line width   

dont impose. common sense. (I have a visible vertical line at 120 in my IDE).

- since tag

kinda unfamiliar with these "java doc feature". Might be useful

-- Miscellaneous --

You often hear people complaining about the verbosity in Java. Most of the time I agree.

Therefore I like the following non-standard non-conventional java coding style (heavily inspired by Scala)

from o.d.i.t.Timeout.java

private final AsyncCallback nopCb = new AsyncCallback() { @Override public void onCallback() { /*nop*/} };

instead of

private final AsyncCallback nopCb = new AsyncCallback() { 

    @Override 

    public void onCallback() { 

        /*nop*/

    } 

};

Iam also voting for one line functions if they are only a single statement, eg.

public long getTimeout() { return timeout; }

So the comments above are all my personal opinions (and I guess they are reflected in the Deft's current code base)

I guess you don't agree with everything, so dont hesitate to raise your voice. I know we can sort this out and get a descent coding convention for deft. :)

// Roger Schildmeijer 

<deftcleanup.xml><deftcodetemplate.xml><deftformatter.xml>

[Johnathan Meehan]

Here are the templates I used in my last commit. Don't know how much it's changed since last time and I'm sure it doesn't have everything asked for - just add and repost.

[Johnathan Meehan]

Something wrong with the code template. Hopefully this one is okay...

[Roger Schildmeijer]

Just realised I never looked at the xml files last time, sorry. 

Would be nice if we settled the coding standard in a near future.

/ Roger

<deftcleanup.xml><deftcodetemplate.xml><deftformatter.xml>