Code conventions

From OpenNMS
Revision as of 13:51, 6 April 2011 by Jeffg (Talk | contribs)

Jump to: navigation, search

Our Java coding conventions are based on the Java standards from the ArsDigita Engineering Standards. The ArsDigita standards themselves are based on Sun's Code Conventions for the Java Programming Language. The ArsDigita standards go beyond the Sun standards and make the code look better, increasing readability, which is very important in my book (I want to be able to read a page of code like I can read a page of prose).

OpenNMS extensions to the ArsDigita standards

  1. Ignore the "Avoid creating objects unnecessarily" performance optimization suggestion in section 1.16.1.1. of the ArsDigita standards. This is not needed in modern and even semi-modern JVMs, and can actually hurt performance.

The File:ArsDigita.eclipse formatter.xml.txt file can be used in Eclipse for this. You'll probably need to rename it to remove the .txt extension before use.

FWIW, here's an article in IBM's developerworks library about Java "Urban performance legends."

For DAO's see DAOConventions

Using the code conventions with Eclipse

First, I highly suggest you read at least the ArsDigita standards at the above link.

Eclipse Code Style variable names

  1. Choose "Eclipse" (or "Window") -> "Preferences...".
  2. In the left-hand pane in the new "Preferences" window that comes up, open the "Java" element, then select "Code Style".
  3. Click on the "Prefix list" column for the "Fields" variable type and set the "Prefix list" to "m_" and click "OK".
  4. Click on the "Prefix list" column for the "Static Fields" variable type and set the "Prefix list" to "s_" and click "OK".
  5. Select "OK" in the bottom right-hand corner of the "Preferences" window to save the preferences.

Eclipse formatting profile

If you are using the Eclipse IDE, you can use the information below to modify the built-in Sun Java Conventions formatting profile to create a custom ArsDigita profile, and use that to format your code.

Hint: just in case Eclipse does a "non-graceful garbage collection" after you make these changes, you'll probably want to exit Eclipse so that these settings get saved to disk, then restart Eclipse and continue on with your work.

  1. Choose "Eclipse" (or "Window") -> "Preferences...".
  2. In the left-hand pane in the new "Preferences" window that comes up, open up the "Java" element, then "Code Style", and select "Formatter".
  3. In the "Formatter" pane on the right, click the "New..." button.
  4. In the new "New Code Formatter Profile" window that comes up, enter "ArsDigita" as the "Profile name" and choose "Java Conventions [built-in]" from the pull-down list for "Initialize settings with the following profile:". Make sure the check box for "Open the edit dialog now" is checked, and hit "OK".
  5. Go through the tabs listed below and change the settings as documented here.

"Indentation" tab

"General settings" section:

  • Tab policy: Spaces only
  • Indentation size: 4

"Line Wrapping" tab

"Line width and indentation levels" section:

  • Maximum line width: 78
  • Default indentation for wrapped lines: 2
  • Default indentation for array initializers: 2

"Function Calls" section:

  • Arguments
    • Line wrapping policy: Wrap only when necessary
    • Indentation policy: Indent on column
    • Force split: unchecked
  • Qualified invocations
    • Line wrapping policy: Do not wrap
    • Indentation policy: (not modifyable)
    • Force split: (not modifyable)
  • Explicit constructor invocations
    • Line wrapping policy: Wrap only when necessary
    • Indentation policy: Indent on column
    • Force split: unchecked
  • Object allocation arguments
    • Line wrapping policy: Wrap only when necessary
    • Indentation policy: Indent on column
    • Force split: unchecked
  • Qualified object allocation arguments
    • Line wrapping policy: Wrap only when necessary
    • Indentation policy: Indent on column
    • Force split: unchecked

"Expressions" section:

  • Conditionals
    • Line wrapping policy: Wrap all elements, except first element if not necessary
    • Indentation policy: Indent on column
    • Force split: unchecked

"Comments" tab

"General settings" section:

  • Enable header comment: checked

"Javadoc comments settings" section:

  • Clear blank lines in comments: checked (note: this seems to have changed to Remove blank lines as of Eclipse 3.3.2)

"Line width" section:

  • Maximum line width for comments: 78

Other references

We aren't using these standards, but they might be useful to look at and consider integrating some of their features into our standards.