Dain Sundstrom kirjoitti:
On Oct 30, 2008, at 1:09 PM, Alex Grönholm wrote:
Dain Sundstrom kirjoitti:
On Oct 29, 2008, at 10:44 AM, Alex Grönholm wrote:
Formatter:
- max line width is 100 characters
I prefer 120, but as long as it is only suggestion it isn't a big
deal for me.
I don't how you do your editing, but in my case, 120 characters is
already so wide that I frequently have to shift my eyes horizontally
to read the whole line, and it doesn't fit on my editor window (with
1600x1200 screen size).
I expect many other developers to have even smaller screens, so I
figured 100 characters would be a reasonable suggestion.
But like you said, it's just a recommendation.
I find that long lines are typically exception messages or methods
with long args. In the vast majority of cases, the details are not
important.
Cleanup:
- always use braces with control statements (I actually disagree
with this, and it's not even consistently used in existing code)
One line if statement should be allowed. For example,
if (debug) System.out.println("This is a one liner");
I strongly recommend that the actual statement be put on a second
line with an extra unit of indentation, like:
if (debug)
System.out.println("This is a one liner");
for readability. Makes it really clear it's a control statement there.
I have strong feelings the other way, and more importantly, I have
strong feelings that any multiline control statement use braces, like:
if (debug) {
System.out.println("This is a one liner");
}
I do not understand why the braces are necessary when the code block is
only 1 line long. I used to do that years ago but over time I came to a
decision to drop that practice since it didn't increase readability (to
the contrary in fact) and it didn't particularly prevent any coding errors.
- removes unused imports and local variables
Order and grouping of import should be specified. I use the following:
java.*
javax.*
<blank line>
others
I like this because it puts the important imports closest to the code.
Works for me. I didn't think it was important so I didn't initially
include that.
It is important so that reformatting doesn't result in huge changes in
import blocks.
But this contradicts what you just said. If we include imports
organization in the cleanup tasks and the imports are not already in the
desired order, it will potentially cause big changes in import blocks then.
- removes "this" qualifier for non-static method/field accesses
(where possible)
- adds missing @Override/@Deprecated annotations
I don't like the @Override annotation in most cases. The only place
I have used it is when doing complex subclassing of the SFSB
container in geronimo, where it helps catch interface changes. In
openejb we typically don't do complex subclassing since it is so
brittle, so the @Override annotation just becomes annoying.
At least Eclipse inserts @Override automatically when you use the
"Override/implement superclass methods" function from the Source
menu. Even if you manually override something, two mouse clicks will
insert the annotation. If all else fails, you could just use the
cleanup function. I would guess IDEA has similar functionality to
this, but I don't have it.
IDEA can be set to do that also, and I would suggest that the feature
should be off for OpenEJB. If a user wants to know something is an
override, they can simply look at the gutter notes in the IDE.
Similarly, the auto generated javadocs in eclipse should be turned off.
The @Override annotation is not used as a marker that the method
overrides something, but as an additional safeguard that alerts the
developer (by giving a compiler error) if the method no longer overrides
a superclass method. This is far more useful with interfaces, but since
@Override only works with interfaces in Java 6 and we are targeting Java
5, this is admittely not as important.
- removes unnecessary casts
- removes trailing whitespace
- corrects indentation
Code templates:
- for newly create .java files, inserts the ASL comment to the top
Also, in general, I dislike aligned text because it becomes a burden
to maintain over time. There are places where it is nice
(specifically simple look tables), but I find it annoying in javadoc
comments and parameter declarations.
I don't think I suggested that anywhere, or maybe I misunderstand
you. Could you please elaborate?
You didn't, but I wanted to explicitly call that one out (that is how
much I dislike it).
One more thing about javadoc formatting -- what it does is this:
/**
* Method description
* @param foo string to indicate "foo"
*/
is formatted to
/**
* Method description
*
* @param foo
* string to indicate "foo"
*/
Helps readability in situations where you are editing the method/class
itself so its javadocs aren't displayed by the IDE in a tooltip or similar.
-dain
