Difference between revisions of "Triquetrum/Coding Style"

Latest revision as of 15:54, 7 September 2016

Coding Conventions

In general, we follow the Eclipse Coding Conventions, with the following changes:

• indentations are 2 spaces, no TABs
• longer lines (160 chars)

CamelCase variable and method names are preferred over underscores.

Disabling Formatting

See http://stackoverflow.com/questions/1024886/making-eclipses-java-code-formatter-ignore-comments for how to use

 // @formatter:off

and

 // @formatter:on

To disable and reenable formatting for block comments. Note that for this to work the formatter settings have to have on/off tags enabled. The formatter settings checked in to the repository have on/off tags enabled.

Settings

As a Triquetrum workspace consists of many projects, we set up the style for the entire workspace as opposed to configuring each project.

Configuring Eclipse Formatter Preferences for Triquetrum

If you intend to submit a pull request, please set your formatter preferences as follows:

1. Open the Formatter preferences: Under Mac OS X, Eclipse -> Preferences -> Java -> Code Style -> Formatter
2. Click on Import
3. Browse to org.eclipse.triquetrum.common/triquetrumFormatterSettings.xml and import it

Configure the Formatter Preferences By Hand

If you choose not to import the settings file above, then below are the steps necessary to configure the formatter:

1. Open the Formatter preferences: Under Mac OS X, Eclipse -> Preferences -> Java -> Code Style -> Formatter
2. Click on New, then enter a name like "Triquetrum Code Style Formatter". Keep the default initialization on "Eclipse [built-in]". Click OK
3. In the Profile window make the following changes
   1. In the Indentation tab (Erwin is the primary developer of Triquetrum and prefers two space indents):
      1. Tab Policy: select "Spaces Only"
      2. Indentation size: 2
      3. Tab size: 2
   2. In the New Lines tab (Christopher likes to run scripts on source files, so they need newlines):
      1. Click on "at end of file"
   3. In the Line Wrapping tab (Erwin likes long lines):
      1. Maximum line width: 160
   4. In the Comments tab:
      1. Maximum line width for comments: 160
   5. Then Click on OK

Configuring Eclipse Clean Up Preferences for Triquetrum

Cleaning the code is a good idea. If you intend to clean the code, make the following changes:

1. Open the Formatter preferences: Under Mac OS X, Eclipse -> Preferences -> Java -> Code Style -> Clean Up
2. Click on Import
3. Browse to org.eclipse.triquetrum.common/triquetrumCleanUpSettings.xml and import it

Configure the Clean Up Preferences By Hand

If you choose not to import the settings file above, then below are the steps necessary to configure the clean up facility:

1. Open the Formatter preferences: Under Mac OS X, Eclipse -> Preferences -> Java -> Code Style -> Clean Up
2. Click on New, then enter a name like "Triquetrum Clean Up". Keep the default initialization on "Eclipse [built-in]". Click OK
3. In the Profile window make the following changes:
   1. In the Code Organizing tab:
      1. Format source code: checked
      2. Remove trailing whitespace: checked
      3. Correct Indentation: checked
      4. Organize imports: checked
      5. Sort Members: not checked (this might change in the future)
   2. In the Code Style tab:
      1. Use blocks in if/while/for/do statements: checked (Blocks in if statements make it easier to avoid bugs that occur when a second line is added to just after the if statement)
   3. In Unnecessary Code tab:
      1. Remove unused private members: checked
      2. Remove unused local variables: checked

Cleaning up the code

1. Important: Before cleaning the all the Triquetrum code, consult with the team to be sure that they have no open branches.
2. Check out a new branch.
3. Set up both the cleanup and formatter preferences as above.
4. Switch to the Java Perspective with Window -> Perspective -> Open Perspective -> Java.
5. Select all the packages.
6. Right click and select Source -> Cleanup.
7. Review the changes.
8. Accept the changes.
9. Commit and push.

See Also

• Triquetrum/CONTRIBUTING.md - How to contribute to Triquetrum.
• Coding Conventions
• Eclipse Incubation Mailing List discussion about coding style