The Apache FOP Project

The Apache™ FOP Project

Apache™ FOP Development: Coding Conventions

Acknowledgement: Some content in this guide was adapted from other Apache™ projects such as Avalon, Cactus, Turbine and Velocity.

Subversion Repository

Conventions in this section apply to Repository content, regardless of type:

Java

Java Style

In order to facilitate the human reading of FOP source code, reduce churning in code, and prevent disputes, 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:

Convention Rationale Enforced By
Every Java source file starts with the Apache licence header. Required by Apache. checkstyle
No tabs in content. Programmers should not have to adjust the tab settings in their editor to be able to read the source code. checkstyle
Indentation of 4 spaces per level. Maximize readability. Not enforced
Comments, identifiers, and project documentation must be in English. In general, other languages must not be used, except in translated documentation and language-specific i10n files. To avoid the need for everyone to learn all languages, English has become the standard language for many technology projects, and is the only human language that all FOP developers are expected to know. Not enforced
American English spelling should be used. Alternative spelling and idioms are tolerated, but may be changed by anyone to American. Some standard is useful, and American English is widely used and accepted for technology standards and projects. Not enforced.
Fully qualify all import statements (no "import java.util.*") Clarity checkstyle
No underscores in variable names except for static finals. Upper/lower case distinctions can be made in all other variable names, eliminating the need for artificial word boundaries. checkstyle
Opening brace for a block should be on the same line as its control statement (if, while, etc.). Standardization, general preference. checkstyle
Write appropriate javadoc entries for all public and protected classes, methods, and variables. Basic API documentation is needed. checkstyle
By ASF policy, @author tags are officially discouraged. However it is permissible to indicate the original author(s) of an entire file or package in a comment provided it follows the copyright and license header. Attribution of subsequent contributions are recorded by the SVN commit history logs, so should not be included. checkstyle

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.

Checkstyle

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.

Java Best Practices

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

Resources

XML

Convention Rationale Enforced By
XML files must always be well-formed. Validation is optional. Document integrity Not enforced
No tabs in content. Users should not have to adjust tab settings in their editor to be able to read the content. Not enforced
Indentation of 2 spaces per level Maximize readability Not enforced