Hello again,
Over the past few months I have been looking over some different areas of
the JBoss source and have found that the style and conventions in use
are wildly divergent. I think that this project (and really any project
were there are multiple developers involved) can benefit greatly from
a common set of coding standards.
I understand that this topic is touchy and I want to press that I am not
trying to start any religious wars. I do believe that by adhering to a
set of guidelines that we can be more productive, enable a general better
understanding of each component, engage other developers to contribute
as well as make the current code base dramatically easier to maintain.
That said, I do not know what those standards should be. There are several
document available on the that cover this subject. I have read some of
them, and tend to agree with parts and disagree with others. I have not
yet found a single document that expresses my own desire for a coding
standard.
So rather than suggesting that we spend weeks debating what the exact
coding standard is I suggest that we make use of the existing documents
with emphases on a few crucial areas:
o Indentation
o Construct declarations
o Documentation format
o Naming conventions
I know that this sounds like a lot, but what I suggest is conformance to
a few areas, leaving it up to the engineer to ultimately make the choice for
what is right for them (and the project).
First I would encourage each of you to look over some of the available
resources on this matter:
http://openjms.exolab.org/ExolabJavaConventions.pdf
http://www.AmbySoft.com/javaCodingStandards.pdf
http://java.sun.com/products/jdk/javadoc/writingdoccomments/index.html
http://java.sun.com/docs/codeconv/html/CodeConvTOC.doc.html
I have looked over all of these at one point, most recently I looked
at the Exolab document, since it is nice and to the point. The AmbySoft
doc is rather large, but contains lots of information, and is and
interesting read if you have the time.
I would like to suggest that we use something like the Exolab document
with some key emphases on the areas I listed above.
Why these areas? I believe that this encompasses most of the common style
issues that most developers will encounter. They are also areas which I
have seen the most difference in usage. I think that if we can agree on
a common usage for each that the codebase will be easier to maintain,
understand and modify.
Indentation, this is by far the most important area to standardize. When
some developers use tabs, others uses 4 spaces and yet others use 3 spaces,
we have a visual interpretation problem when any given developer tries
to understand or maintain others code. The most common problem is when a
file has been indented with both tabs and space, leaving the formatting in
disarray for any other developer who's editor was not configured to handle
the formatting the same.
I personally like 3 space (2 is too little, 4 is too much), but most other
standards suggest 4, so I would probably switch to 4.
Construct declarations is a close second to indentation. I personally find
this the most disruptive to understanding code written by another. This
combined with poor indentation consistency provides for highly illegible
source code. The Exolab document provides a good standard that I think we
should follow on this. Specifically the location of braces and spaces is
important to be consistent with. For example
if ( a == b )
{
whatever(a);
} else if(a>= b ) {
whatever( b );
} else {
for( int i = 0;i<=5 ; i++ )
{
try {
whatever(i);
}catch(Exception e) {
}
}
}
vs.
if (a == b) {
whatever(a);
}
else if (a>= b) {
whatever(b);
}
else {
for (int i = 0; i<=5; i++) {
try {
whatever(i);
}
catch (Exception ignore) {}
}
}
I think that second is vastly more readable and understandable.
Standardizing documentation styles is also very important, as it makes
it much easier for other developers to read, as well as possible
write or update documentation for code that has been written by others.
The document from Sun on this subject is basically the bible on this
matter and I would suggest following most of its lore.
Lastly, is naming conventions. Different developers are used to different
standards. Some Microsoft folks are tied to the mXXX standard for
member fields, some to <type>XXX (where type is some soft of short prefix
like d for decimal or i for integer) others like to prefix there members
with _ and still other like to leave them as is and use 'this' to resolve
any namespace collisions.
Package, class and factory method naming conventions are also very important
to settle on. By settle I mean listing which conventions are acceptable
and which are definitely not. I believe that it is important to allow
developers the freedom to choose... but that there should be a static
range of choices. I personally have gone from using _XXX to this.XXX
and could really go either way.
If possible I would suggest that we make use of the Exolab doc (assuming
that they don't mind) and provide some JBoss specific comments on the
application and usage of it. If not, then I would suggest something very
similar to that document.
Any ways, I really wanted to express this to the group as something that
would be highly beneficial to the progress of this project. I would like to
know what you think about this, so if you have any questions or comments...
let 'em fly... but lets not start a war.
--jason
_______________________________________________
Jboss-development mailing list
[EMAIL PROTECTED]
http://lists.sourceforge.net/lists/listinfo/jboss-development
