This has bugged me for a while, but now that we've got several new
developers joining for the Google Summer of Code, I'm motivated to get it
resolved.
Currently the way we work is that everyone follows the coding conventions to
the degree that they wish (or that their tools easily support) and then
Linus periodically goes around and reformats everything to his liking.
There are three problems with this: 1) it doesn't scale, 2) Linus has much,
MUCH more important things to do, and 3) it creates code churn which is one
of the main things that coding conventions are designed to fix.
I'd like to see the following changes:
1. revise the coding conventions to something that we'll ALL use (and are
easily supported by our tools) 2. come up with a set of
Eclipse/Emacs/whatever settings that support our conventions 3. enforce
conformance by asking the author to make revisions to non-conforming commits
rather than changing their code for them 4. when reformatting old code,
make the minimal change which will bring the code into conformance 5. Stop
mechanically resolving checkstyle warnings without adding value - this just
masks real problems
(e.g. adding comments like /* Constructor */ or Javadoc @param tags with
no contents)
I'm fundamentally lazy, so I'm going to accept the way Eclipse formats the
code 95% of the time and anything not flagged by Checkstyle probably isn't
going to get fixed. I suspect others are the same, so it doesn't make any
sense to adopt conventions which aren't supported by our tools.
As far as changes to the conventions themselves go, I hate debating this
stuff, so I'm willing to accept anything that Eclipse will support, but the
following are some observations about our current practices (written and
unwritten):
- Eclipse shows the constructor Javadoc for its tips, so we need to
encourage people to make them descriptive. A comment of /* Constructor. */
is useless.
- Why is the 2nd form better than the first below? If we are going to
require #2, let's come up with the Eclipse settings that will make it wrap
things that way (it does #1 by default).
#1: for (Iterator iter = modelImpl.getModelPackage().getMofClass()
.refAllOfClass().iterator(); iter.hasNext();) {
#2: for (Iterator iter =
modelImpl.getModelPackage().getMofClass().refAllOfClass()
.iterator();
iter.hasNext();) {
- I don't see how expanding the concise single line of #1 below to 4 (!)
lines adds any value at all :
#1: subkeys = new String[] {""};
#2: subkeys =
new String[] {
"",
};
- Non-Javadoc comments are getting changed to Javadoc versions for private
fields and methods which seems wrong to me. Isn't this just going to
clutter the Javadoc with irrelevant information? Note I'm not saying things
shouldn't be commented, just arguing whether we should be promoting the
comments to Javadoc status.
- Is it really significant whether we have <p> in Javadoc at the end of one
line or the beginning of the next? Do we really need to keep moving these
around? I don't think there's an Eclipse setting to control this, so I'd
really REALLY prefer to see wherever Eclipse puts them be a legal option.
- Checkstyle (or the compiler?) is warning about missing serialization
versions for classes that implement Serializable. My understanding is that
without the version number, Java may think things are incompatible when they
really are still compatible. Personally I don't think that's a big deal. I
also doubt that we have the discipline to maintain the version #
appropriately for changes to the public API. I've added some of these to
make the warnings go away, but I think a better option would be to disable
the check.
Tom
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
