Coding Standards for Alfresco Content Services

[resplin]

• Code formatting
• Java Coding Standard
• Deviations
• Eclipse
• Logging
• General Coding Practice
• Style
• Other Standards

If you are interested in making a contribution to a project that makes up Repository within Alfresco Content Services, you should review the instructions on the page Submitting Contributions‌.

For your contribution to be accepted, it needs to fit in with the rest of the code base. Following these guidelines will significantly improve the odds that your contribution becomes a part of the project, but it does not guarantee that your contribution will be accepted; it also has to fit in with the vision and direction for the project.

Code formatting

• Charset is UTF-8
• Line endings are CRLF (the Governance Services RM module uses LF)
• All braces are on new lines (except for lambda expressions)
• The braces are enforced everywhere even if not explicitly required
• The multi statement constructions like *try-catch-finally* have each statement on new line
• Wrap code at 255 characters
• Tabs are substituted with 4 spaces
• Empty lines do not have tabs/spaces
• All new classes, methods and fields have JavaDoc
• The JavaDoc should be compliant with Java8 DocLint at http://openjdk.java.net/jeps/172 
• The strings which are shown to the user (in the UI) should be put in localization property bundles. Our localization team will handle the translations if required.
• Properties files should be ISO-8859-1 encodedor at least encoded with native2ascii for characters that are not part of that encoding.

Java Coding Standard

• The core of our coding standards are the standard Java Code Conventions.
• XML documents are properly indented with 4 space tabbing (note: some still use 3 space tabbing).

Deviations

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

Eclipse

Much of the team use IntelliJ, but these guidelines for Eclipse help adopt our coding standards.

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

When generating a log message:

• 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.

Newer code (such as the Governance Services RM module) uses SLF4J to make sure that all logging output is handled in a uniform manner. It is not necessary to check that logging is enabled before generating a message.

Older code uses the Apache Commons Logging API. A guide is available on the Apache Common Logging website. When using Apache Commons Logging, wrap all logging calls (logger.debug, logger.info, logger.trace) with a check that the log level is enabled (logger.isDebugEnabled, logger.isInfoEnabled, logger.isTraceEnabled). This avoids generating log messages that will be discarded.

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 but these should be decreasing over time.

• Readability
  • It must be easy to read and understand the code
• 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
• Object state
  • It shouldn't be possible to instantiate an invalid state of an object
    • Avoid default constructors if the class has mandatory fields
    • Avoid public setters for read-only fields

Style

• Order imports: standard JDK imports first (in alphabetical order), then non-JDK imports (including org.alfresco, also in alphabetical order).
  • the RM settings can be found in the ide-config folder in the root of the project.
• Method order is: Constructor(s), Spring setters, Spring init method, 'Vanilla' methods.
• No-op methods are allowed.
• Whitespace before and after code blocks (if, for, while, do, etc. statements) is optional.
• Group code blocks logically

Other Standards

You might find these guidelines for other Alfresco projects to be useful:

• JavaScript Code Standards‌
• Alfresco REST Design Guidelines‌
• IOS Coding Standards‌
• Community Coding Standards‌

• Aikau contribution guidelines standards  https://github.com/Alfresco/Aikau/wiki/Contribution%20Acceptance%20Criteria
• Order of the Bee Coding add-on guidelines https://github.com/OrderOfTheBee/addons/wiki/Inclusion-criteria-overview