As you may support, it is important to have/use one single common code style. This style should offer the best possible readability for all. So far some different code styles have been used in the xith codebase. I’ve been talking with Amos about that and so far he accepted all of my justified suggestions. I’ll sum them up here and we can discuss about them. When the majority of everybody willing to contribute to Xith3D or Xith-TK agreed to them, we can introcuce them as the common coding guidelines.
-
Braces (putting the opening-brace at the beginning of the next line):
The advantages of putting the opening-brace at the beginning of the next line is simple to descibe but very important:
[list]
[li]It is much more structured, since you can easily see from position of the braces, where a block begins and where it ends (espeacially where it begins). - It forces you to leave a blank line between the signature and method body. Well, this is done anyway by most people. But why then not simply put the opening brace at the begining of the next line???
- And it provides a better, nicer look of the coding, which is of course subjective.
Putting the opening-brace at the end of the signature sometimes seems to me like the search for an answer for the question “Where to put this lazy opening-brace?”. But putting it at the beginning of the next line is “using it as a tool for improving the code structure” as it is meant to be.
[/li]
-
indentation:
Indetation must start with zero, then all lines are to be indeted (hierarchically) by 4 spaces. This also means, that no tabs are to be used, since tabs are differently displayed in different environments. And of course the empty lines are to be indeted, too. This is nothing one will directly see, but it helps a lot when adding new lines next to these empty lines. -
line wrapping:
By standard Eclipse wraps lines at column 80, which is somewhat old, since we nowadays have larger resolutions and are not forced to work on a 80 columned DOS screen. The automatic line wrapping whould be switched off (set to a large value like 1024). If I ever want a line to be wrapped, I’ll do it manually when I type the line. No need to wrap a line, if it has 81 columns.
However JavaDoc comments should be wrapped by column 80, since it is readable block text, which provides a better readability if wrapped at column 80. -
white spaces:
The parameters of method calls should be spaced by one space after the opening bracket and one before the closing bracket like this:
[/list]
myMethod( arg0, arg1, arg2 );
I myself needed some time to acclimate with this, but at the end it again provides an even better readability. Well, if Eclipse is configured like this, it will produce code like this:
myMethod( a( b( c( myFunction( p0, p2, p3 ) ) ) ), arg0, arg1, arg2 );
Which is a little bloated. So decide on your own, where to let eclipse format the code, and where you want to have it a little more campact. But at least when you have one braced arguments list, space it.
Return statements are to be spaced and braced, too, since it just fits into the whole system, as well as throw statements, even if Eclipse code formatter doesn’t fully support it. Do it like this:
public void myMethod1()
{
throw( new IllegalArgumentException("bla") );
}
public String myMethod2()
{
return( "bla" );
}
-
JavaDoc:
Of course it is a good idea to always create JavaDoc tags, when you create a new class. Never commit an uncommented class. Try to use abstract texts, which say more than “Does XXX” for a doXXX() method, if it does more. -
visibility:
Try to give a class or method as less visibility as possible. This means, make a method private, if it is logically private (never used from outside). Keep in mind, that no-modifyer is not private! It is the same as protected, but is not visible in subclasses. -
Make use of class hierarchy:
If you want to use a Vector, HashMap, Point3f, etc., consider, if you need the additional methods the concrete class offers compared to an implemented interface like List, Map, Tuple3f. If you don’t need them, just define the variable or (more importantly) the parameter as the interface type. This gives you the advantage, that you’re free to choose the conrete class or in case of parameters gives the users the freedom to choose, which is a real big benefit.
This is mostly already done and has less to do with code formatting, but I thought it would be good to list it here, too.
If I forgot anything, I’ll edit this posting and add it.
I created an Eclipse code formatter export file. So you don’t need to configure your Eclipse on your own. It would be very nice, if one of you NetBeans users could send me a file for NetBeans. I’ll then attach the file to this posting, too. Don’t know, if NetBeans even supports code formatting.
You can download the formatter export file from Xith3D Code conventions page.
Marvin
