|
About half of programmer's world nowadays prefers to support good readability
over code compression. In ancient times it was necessary to compress code to get
as much code visible on an 80x24 terminal.
Today where we have much larger resolutions, we can spend some space on readability
and still have a sufficient amount of code visible at a time.
The following guidelines will help in this intention and are the way to go for the Xith3D projects:
-
Braces:
The Opening-Brace must be placed at the beginning of the next line to match
the same column as the corresponding closing-brace.
This makes it much easier to find matching braces and generally improves code structure.
-
Indentation:
Indentation must start with zero, then all lines are to be indented
(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 indented, too.
-
White spaces:
Place a space after the opening parenthese and one before the closing parenthese
for method calls, conditions, etc.
Return statements are to be spaced and parenthesed, too, and a space is to be placed before
the opening parenthese.
Put one space before the opening parenthese of the headers of
for, while, if,
catch, etc. statements.
-
Line-Wrapping:
Regular code doesn't need to be wrapped anywhere by rule.
But make sure that lines don't get too long.
JavaDoc doesn't necessarily have to be wrapped at column 80, but should be kept in a thinner column to be easily read.
-
Visibility (Encapsulation):
Try to give a class or method as less visibility as possible / necessary.
This means, make a method private, if it is logically private (never used from outside).
Keep in mind, that no-modifier 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 an ArrayList, HashMap, Point3f, etc. and you don't need
the additional functionality, the concrete class offers compared to an implemented
interface or superclass like List, Map, Tuple3f, make sure, that the user is able to
use the setter / method / etc. with the most basic type, that's possible.
This rule has one exception: If it is performance criticle code, try to use
the concrete types to ensure, that inlining can be performed.
-
JavaDoc:
Of course it is a good idea to always create JavaDoc tags, when you create
a new class or method. Never commit an uncommented class.
Try to use abstract texts, which say more than
"Does XXX" for a doXXX() method, if it does more.
-
License headers:
Each class committed to the project must carry the license header
to be found and copied from any existing file.
Here is an Eclipse Code Formatter configuration for it (Eclipse 3.4 and above).
|
