Coding Standards

Document created by resplin Employee on Mar 27, 2015Last modified by derek on Feb 14, 2017
Version 3Show Document
  • View in full screen mode

{{Needs Work}}

DevelopingCommunity

 

Scope

 

These are the standards used by the Alfresco Engineering team for development on the core applications, and should be followed when submitting changes for inclusion into core.

There is another page documenting optional standards for add-ons and community driven efforts.

These standards reflect how we want the code to be, not necessarily how it currently is.

 

Java Coding Standard

 

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

File Formats

 

  • UTF-8 encoding of all text files
  • Windows line endings (CR-LF)

Deviations

 

  • Braces are on new lines
  • 4 spaces for a tab
  • Variable declarations may occur anywhere in a method body.

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'

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.

 

  • 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.  The majority of other informative messages are DEBUG.  Certain fine-grained debug may be TRACE.
  • Put as much context and formatting into the message as time will allow.
  • Wrap all calls to logger.debug and logger.info (as well as logger.trace), i.e. all code that will be unnecessarily generating messages only to find them not logged, with the appropriate logger.isDebugEnabled or logger.isInfoEnabled (or logger.isTraceEnabled)

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.

 

  • Readability
    • It must be easy to read and understand the code
  • General Formatting
    • Braces on a new line
    • 4 spaces for tabs, except old Web Client project
    • 120 characters on a line is fine.
  • Auto-formatting
    • Do not auto-format existing classes
  • 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.
  • Comments
    • Comments must have a point:
      • do not include references to inherited methods as javadoc does this automatically
      • remove or do not use auto-generated javadoc e.g. /* non-javadoc */ or generated TODOs
    • Classes have a description, 'author' and 'since' information
    • Comments can use the screen space and should not wrap for no reason

Style

 

  • Order imports: standard JDK imports first (in alphabetical order), then non-JDK imports (including org.alfresco, also in alphabetical order).
  • Method order is: Constructor(s), Spring setters, Spring init method, 'Vanilla' methods.
  • Spring setters do not require JavaDoc comments.  All other methods do.
  • No-op methods are allowed.
  • Whitespace before and after code blocks (if, for, while, do, etc. statements) is optional.
  • Group code blocks logically
  • Stateful classes should have a serialVersionUID.
  • When logging, use Log.isXXXXEnabled() before emitting logging output.

REST API

 

A separate page is available covering the recommended guidelines for authoring REST APIs.

 

JavaScript

 

A separate page is available covering the JavaScript guidelines.

Page Needs Work

1 person found this helpful

Attachments

    Outcomes