Code Style Rules
OpenJFX has strict code style guidelines that should be enforced on every changeset. All developers will differ in opinion on every coding convention (tabs or spaces?). However on a large project with many individuals, if it were left to each developer to specify their own conventions, then we would quickly end up with a complete mess for our source code. This extends far beyond spaces vs. tabs (which, by the way, we use spaces) but also includes API design and is one reason why all API must be reviewed before it is integrated. Consistency is vitally important in making an API easy to learn and use.
Our guidelines are based on the legacy Java Code Conventions, although we do not follow it strictly, except for those white-space rules that git jcheck enforces. The Java Code Conventions were drawn up at the dawn of time and are in sore need of a revision! For example 80-character line lengths was probably good advice in 1996, but in 2013 we have w-i-d-e monitors and we also like descriptive method and variable names. This leads to long lines and horrible wrapping when limited to 80 characters. A recommended maximum is 120 characters.
This document captures what rules we use. Any violations of these rules should be corrected either during a code review, or when discovered. By having a single consistent set of rules that we apply throughout the codebase, we make it easier to:
- Use tools to keep things nicely maintained
- Provide patches to any part of the platform
- Bring new developers up to speed
- Avoid chatter during a code review describing code style preferences unique to one part of the platform (we can instead just send a pointer to this document whenever there is a dispute)
- Handle disputes quickly and efficiently
Not everybody will like all of the code style rules, but hopefully most people will like most of them. More important, by following these rules we will have a consistent codebase with all the aforementioned benefits. This is a "living document" and will be amended as we go along. When new issues arise, we will add them to this list.
As mentioned above, some of the white-space rules are enforced by git jcheck. The rest are conventions to which we should all strive to adhere.
Enforced by jcheck
- No trailing whitespace. Most (all?) IDEs can be configured to automatically trim trailing whitespace
- Use Spaces not TABs.
- Use Unix-style (LF) line endings. No DOS-style (CR-LF) line endings.
Encouraged by Convention
- Use 4 space indentation
- Use a single new-line at the end of every file
- Insert a blank line between the Copyright notice and the package statement
- Insert a blank line between the package statement and any import statements
- There should be one blank line between the last import statement and the class documentation