Coding Standards

From AlfrescoWiki

Contents 1 Mainline Coding Standard 2 File Formats 3 Deviations 4 Eclipse 5 Logging 6 General Coding Practice

[edit] Mainline Coding Standard

1. The core of our coding standards are the standard Java Code Conventions. This includes 4 space tabbing, simple member names, etc.
2. XML documents are properly indented with 3 space tabbing. The Eclipse plug-in, XMLBuddy, is generally used.
3. Import declarations are managed by Eclipse's standard ordering rules (CTRL-SHIFT-O). This helps prevent code merge conflicts.

[edit] File Formats

1. UTF-8 encoding of all text files
2. Windows line endings (CR-LF)

[edit] Deviations

1. Braces are on new lines
2. The web client code uses 3 spaces tabs

[edit] Eclipse

Install latest Eclipse 3.x. In Preferences:

• General -> Workspace
  • Set 'Text file encoding' to 'UTF-8'
  • Set 'New text file line delimiter' to 'Windows'

• General -> Editors -> Text Editors
  • Set 'Insert spaces for tabs'

• Java -> Code Style -> Formatter
  • Copy the built in Java standard to a new code style, called for example "Alfresco" ...
  • ... on the 'Indentation' tab, set tab policy to 'Spaces only'
  • ... on the 'Braces' tab, change all to 'Next line' except 'Array initializer'

[edit] Logging

Use the Apache Commons Logging API to make sure that all logging output is uniformed over the different systems, a guide is available on the Apache Common Loggings website.

[edit] General Coding Practice

This section is meant for contributors to our main code streams. Naturally, you will be able to find violations within our own code.

• General Formatting
  • Braces on a new line
  • 4 spaces for tabs, except Web Client project
  • 120 characters on a line is fine.
• Exceptions
  • When generating a new exception, always attach the cause to it.
  • Don't log exceptions unless you are adding the logic to absorb the exception.
  • Put as much context and formatting into the error message as possible.
  • Use RuntimeException-derived exceptions, unless there is a really good reason to bother the client code with a checked exception.
  • Pay attention to the Javadoc spec on unchecked exceptions. Don't declare them on the interface, just in the javadocs.
• Logging
  • Only Apache Commons Logging.
  • Use the class hierarchy categories, but where deviations are made, add comments to the javadocs.
  • INFO messages are only added at the request of users of Alfresco. All other informative messages are DEBUG.
  • Put as much context and formatting into the message as time will allow.
  • Wrap all calls to logger.debug and logger.info, i.e. all code that will be unecessarily generating messages only to find them no logged, with the appropriate logger.isDebugEnabled and logger.isInfoEnabled.
• Comments
  • NodeRef will always be a reference to a node. Be more specific with the comments.