I like the idea of having a single page to collect the conventions.
For new comers to the project it is nice to not have to guess the
conventions from source. As for the specific conventions, I think we
should split the conventions into requirements like license location,
tab size and curly bracket location, and suggestions such as line
length. I find that when you only have requirements you sometimes end
up with hard to read code because there is no leeway for the author.
Finally here are some style guides I found really helpful:
Sun's JavaDoc style guide - covers everything from formatting to
proper grammar for documentation (e.g, voice selection and when to use
full or fragment sentences)
http://java.sun.com/j2se/javadoc/writingdoccomments/
Sun's Java Code Conventsions - extremely extensive and I like most of
them except for the obvious wacky tabbing rules and 80char line limit.
http://java.sun.com/docs/codeconv/html/CodeConvTOC.doc.html
-dain
On Oct 16, 2008, at 7:09 PM, David Blevins wrote:
On Oct 16, 2008, at 3:48 PM, Alex Grönholm wrote:
What I'm saying is that we need a written set of guidelines so that
freshly contributed code wouldn't have to be constantly
reformatted. A good sized set of example code files would go a long
way towards this goal. If you agree with me on this, we could set
up a Wiki page for contributors where all the necessary
instructions and guidelines would go.
Now that you mention it recall that Maven had a pretty cool approach
to this with a basic doc and then actual IDE config files for
Eclipse and Intellij that people could just install. http://maven.apache.org/developers/conventions/code.html
We could do something like that.
-David
