FOP Development: Coding Conventions

In order to facilitate the human reading of FOP source code, the FOP developers have agreed on a set of coding conventions. The basis of these coding conventions is documented in the Apache XML Project Guidelines, which requires that all Java Language source code in the repository must be written in conformance to Sun's Code Conventions for the Java Programming Language. In addition, the FOP developers have agreed to other conventions, which are summarized in the following table:

For developers that dislike these conventions, one workaround is to develop using their own style, then use a formatting tool like astyle (Artistic Style) before committing.

The java syntax checker "Checkstyle" is used to enforce many of the FOP coding standards. The standards enforced through Checkstyle are documented in its configuration file (xml-fop/checkstyle.cfg). The conventions defined in the configuration file are an integral part of FOP's coding conventions, and should not be changed without common consent. In other words, the configuration file contains additional conventions that are not documented on this page, but are generally accepted as good style within the java community (i.e. they are the default behavior of checkstyle, which the FOP developers have decided to adopt de facto). Any apparent contradiction between the configuration file and this document should be raised on the fop-dev mailing list so that it can be clarified.

To use the "checkstyle" target in FOP's build process, download the source from the Checkstyle web site, place checkstyle-all-*.jar in the lib directory and call "build checkstyle". Output (in the build directory) includes checkstyle_report.txt and checkstyle_report.xml. If you copy the file contrib/checkstyle-noframes.xsl from Checkstyle into FOP's root directory, you will also get an HTML report.

Checkstyle is probably most useful when integrated into your IDE. See the Checkstyle web site for more information about IDE plugins.

The following general principles are a distillation of best practice expectations on the FOP project.

• Apply common sense when coding. When coding keep in mind that others will read your code and have to understand it.
• Readability comes before performance, at least initially.
• If you can refactor some code to make it more understandable, please do so.
• Properly document code, especially where it's important.
• Use interfaces instead of implementations where possible. This favors a clearer design and makes switching between implementations easier (Examples: List instead of ArrayList/Vector, Map instead of HashMap/Hashtable).
• Avoid using exceptions for flow control.
• Try to catch exceptions as much as possible and rethrow higher level exceptions (meaning hiding the low level detailed and putting a message that is more related to the function of your code).
• It is important not to lose the stack trace which contains important information. Use chained exception for that. Avalon Framework provides CascadingException (and similar) for this. Exception class names and stack traces must be treated like gold. Do whatever is required so that this information is not lost. Printing error messages to System.err or System.out is useless in a server-side environment where this info is usually lost.
• Always log the exception at the higher level (i.e. where it is handled and not rethrown).
• Try to avoid catching Throwable or Exception and catch specific exceptions instead.

• [book on code style] Code Complete by Steve McConnell.
• [code formatting software] JRefactory.

• Apache Source Repositories
• Jakarta Code Conventions and Standards (see Coding Conventions and Standards section)
• Avalon Project - Coding Standards