Coding Guidelines

Last modifled 04 Mar 2005

Rules

I've tried to keep the rules to a minimum and make most of the guidelines suggestions.

(1) Package dependencies. (i) Avoid circular dependencies between packages. I.e. if any classes in package A import classes from package B, then classes in package B should not import classes from package A. (ii) Follow the package dependency rules. The checkdep ant script tests compliance. To run it type: ant -f checkdep.xml The script and the html page are generated by the class experimental.GenerateDependenciesXmlAndHtml.

(2) Some of the GUI classes have been created using the NetBeans GUI editor. The .java files for these classes have corresponding .form files. Within the java files are protected sections of code, if you edit these files, please do not alter these sections by hand.

Suggestions

(1) Generally follow the sun java coding converions.

(2) Run all unit tests after making changes to see whether anything has broken. You can do this using the test Ant target.

(3) Check the javadoc Ant target runs without errors or warnings.

(4) Javadoc comments. Add a couple of sentences saying what the class does and the reason for its addition with a date. Also use the @author tag if you add a new class or make a significant change to an existing one.

(5) Use Code Formatters with care. Avoid reformatting whole files with different formatting schemes when you have only changed a few lines.

(6) Consider writing junit tests.

(7) Consider using assertions.

(8) Add //FIXME ..and //TODO comments if you spot possible problems in existing code.

(9) Use logging instead of System.out or System.err for debug messages. Each class should have its own logger, e.g.

private static final Logger logger = Logger.getLogger(SomeClass.class.getName());

Submitting Patches

(1) Small patches that fix one thing, add one feature, or clean up one aspect of the code are generally the easiest to manage.

(2) Run CVS diff with output in 'unified' format. (You can do this in Eclipse by selecting Team -> Create Patch.)

(3) Check list:

(A) Is there patch against the lastest code in CVS? I.e. if you do a fresh CVS checkout of the jfreerails module, does the patch apply correctly.

(B) If you have create new files, are they included in the patch? Look at the -N option.

(C) Are binary files excluded from the diff file? Any new or modified binary files, *.png, *.wav etc, should be included separately.

(D) Do the following Ant targets work without warnings or errors when the patch is applied against a fresh CVS checkout?

ant compile
ant test
ant run
ant -f checkdep.xml
ant javadoc

(E) Does the patch have a meaningful filename? E.g. bug910902_patch1.diff.

(4) Submit patches using the patch or bug tracker on the freerails sourceforge page.

Books

I've found the following useful.

Effective Java (sample chapters online)

Java Platform Performance (available online)

User Interface Design for Programmers (available online)