Linus said:
> I have been stubborn about sticking to the Code
> Conventions for the Java Programming Language from Sun.
but then goes on to describe several "interpretations," additions, and
personal preferences. True to my word though, I'm willing to acquiesce on
any of the mechanical stuff if there is tool support for it. I don't see any
recent updates to eclipse-argo-codetemplates, eclipse-argo-formatter, or
eclipse-argo-prefs. Do you have private versions that you are using? Can
we get CVS updated appropriately?
> For statements also has the peculiarity that the
> initialization and the condition looks like statements. They
> end with ';' and everything. So I prefer writing them each on
> their own line if wrapping is needed.
Preferences are fine for writing new code, but existing code shouldn't be
modified unless it clearly violates the coding conventions in a way that
makes it *necessary* to change it.
> > 4. when reformatting old code, make the minimal change which will bring
the code into conformance
Do you agree that point #4 is a good idea? I think it's important to help
minimize code churn.
> > #1: subkeys = new String[] {""};
> > #2: subkeys =
> > new String[] {
> > "",
> > };
> This is not stated in the Code Conventions. This comes from a
> combination of checkstyle rules (NoWhitespaceAfter (comman,
> left brace) and ArrayTrailingComma) together with the
> "higher-level breaks preferred" as above.
Checkstyle is a tool to help use conform to the Sun conventions, so if
there's a mismatch, that's easy to fix. Even so, I see no Checkstyle errors
or warnings about construct #1 when I run it. What checkstyle file are you
using? Something different from checstyle_argouml in CVS? Also,
NoWhitespaceAfter won't be triggered by #1 because there is no whitespace
after the brace.
> Either the private fields and methods are
> interesting to the person examining the class or they are
> not. If they are interesting, then the javadoc view could
> just as well contain their documentation. If they are not
> interesting, then why should the javadoc contain them at all?
That's precisely the point. The Javadoc *shouldn't* contain implementation
details at all. We use multiple levels of abstraction, but at any level of
abstraction the internal implementation details aren't relevant to the
consumer of the implementation. Javadoc is about the API/interface, not the
implementation. A private method *by definition* can't be used outside the
class. It doesn't belong in the Javadoc.
> If the <p> is put first on a line, the end of that section is
> not as clearly marked. Especially (in some cases that I have
> fixed) where the line with <p> is instead of the empty line.
When you say "fixed" are you saying that this is covered by the Sun
conventions? Is there an Eclipse setting which supports the style you want
to enforce? The disadvantage to enforcing a style not supported by the
tools is that it discourages developers from updating the comments (this is
the reason leading asterisks were discouraged on block comments by most
coding conventions until the tools evolved to easily support rewrapping
them).
If I update a comment and rewrap it using Eclipse, are you going to "fix" it
again? That type of dueling change is exactly the type of code churn that
coding standards are designed to avoid.
Tom
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
