Style guide

🚧 This document is a work in progress 🚧

The coding style conventions that OpenWayback should follow is based on the document Sun's Code Conventions for the Java Programming Language. We have loosened some of the requirements and strengthened others. Most important points are listed below.

Code Style

• Use spaces, not tabs. Tabs should not appear in project source code.
• Indent 4 spaces per level.
• (Deviation from Sun recommendations) Lines should not be longer than 100 columns. Sun recommends 80, but screens have grown larger. Since method and variable names shouldn't be abbreviated, lines tend to be broken too frequently if they are only 80 columns.
• No spaces at end of line
• Files should end with newline
• Place the opening bracket for a code block on the same line as the declaration/test expecting a block.
• Use brackets even when a branch/block is only a single line of code (to provide an additional visual cue, and for robustness if other lines are added later).
• Prefer longs over ints anywhere a large count of artifacts or large-sized file/range is possible.
• Prefer 'package private' (i.e. no modifier) over 'private' unless a consideration of potential subclass use suggests direct access will be dangerous.
• (Deviation from Sun recommendations) It is permissible to declare local variables as close to first use as practical (as opposed to at the start of the enclosing block).
• (Deviation from some recommendations) Early- and multiple- returns from methods are encouraged to minimize indention-levels, and handle simple or error cases quickly.
• All classes must have a Javadoc comment. All public and protected methods should have a Javadoc comment. The use of Javadoc comments for other methods is encouraged, especially if they are more than 5 lines long.
• Do not include @author in class documentation. Since a class might have many edits from different authors, an author annotation for the class doesn't say much. Instead you can use the blame function on GitHub to find who wrote what.
• Avoid broad catches (of all Exception or all Throwable) where possible. (Testing code and other all-or-nothing situations excepted.)

Tip

This style guide was not enforced from the start and therefor it might sometimes be difficult to sort out real changes from changes in formatting, especially changes in white space. Everywhere on GitHub where there is a diff view (like in pull requests) you can add ?w=1 at the end of the line to ignore changes in white space from the view.