Dain Sundstrom kirjoitti:
On Oct 30, 2008, at 1:58 PM, Alex Grönholm wrote:
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.
Not for me. I find it easy to make programming mistakes and it is
hard for me to read.
I on the other hand have strong issues with the one-liner you presented.
Maybe we could agree to use braces for all control statements then? It
takes up more space but at least neither of us would question its
readability aspect.
- 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.
In the short term. More importantly when a programmer does reformat
the code it would like them to end up in a predefined and consistent
order.
I think the best I could come up with is:
java.*
<blank line>
javax.*
<blank line>
others
Would this be acceptable?
- 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.
I understand how the annotation works, and I find it useful in the way
it was originally intended, to force the compiler to throw an
exception when a method is no-longer an override. The common use as
documentation, brought about by the over zealous eclipse IDE, is
simply annoying and better served by gutter notes in an IDE.
I think we are in agreement that it's unnecessary as a means of
documentation, but I would still like to keep it for safeguard purposes.
- 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"
*/
Yuck.
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.
I don't know what you are talking about. Intellij doesn't do that.
-dain
Oh well, I'm not going to insist on that :P
