Coding Rules

This page collects rules which should make ARC a high quality software package which is easily maintainable by several several developers.

Naming

File names

Bear in mind that both code and documentation MUST be available on case insensitive file systems.

Do NOT use file names differing only in letter case.

Code layout

C++ template

C++ files must have the following layout:

 #ifdef HAVE_CONFIG_H
 #include <config.h>
 #endif
 
 // System C++ headers (no C headers)
 #include <string>
 #include <cstdlib>
 #include <cstdlib>
 
 // System C headers (which have not C++ counterpart)
 #include <fcntl.h>
 
 // External applications/library headers not necessarily distributed
 // with the system
 
 #include <openssl/sha.h>
 #include <glibmm.h>
 
 // ARC installed headers
 #include <arc/XMLNode.h>
 
 // ARC local headers
 #include "OtherClass.h"
 
 // Class header
 #include "MyClass.h"
 
 namespace MyNameSpace {
 
 }

if/while/for blocks

If if/while/for block takes more than one line, curly brackets must be used. The reason is that it is easy to break code by adding one more line of code and unintentionally forgetting to add brackets.

This is bad:

 if(a > b)
   a = b;

This is right:

 if(a > b) {
   a = b;
 }

And this is right too:

 if(a > b) a = b;

Printing output and error messages

logger.msg is the correct way to print something, either to standard output, or to a log file, e.g.:

#include <arc/Logger.h>
...
  logger.msg(ERROR, "Failed configuration initialization")
...
  logger.msg(VERBOSE, "Assigned to VO %s", vo)

Following logging levels for tagging and filtering log messages exist:

• FATAL level designates very severe error events that will presumably lead the application to abort.
• ERROR level designates error events that might still allow the application to continue running.
• WARNING level designates potentially harmful situations.
• INFO level designates informational messages that highlight the progress of the application at coarse-grained level.
• VERBOSE level designates fine-grained informational events that will give additional information about the application.
• DEBUG level designates finer-grained informational events which should only be used for debugging purposes.

IString, etc. are used from inside Logger.

cout << and cerr << are wrong way unless really really needed - like to avoid formatting.

Testing

ARC uses CppUnit for Unit testing. All C++ classes must have an associated unit test. On the Unit Testing page you can see an example on how to setup the framework for a class.

Documenting

Code changes

Every code change must be documented!

Commit comments

Provide clear details in commit logs. "Oops" or "reverting bad commit" are not valid commit log entries. Describe which component was changed (e.g., client library, a plugin, A-REX, HED etc).

If the change fixes a reported bug or implements a requested feature, always provide bug report (or feature request) number.

ChangeLog

ChangeLog file is located in the trunk

Please use this file to record significant changes, which make difference from the previous version, especially those which break compatibility or introduce new features. Please keep updating the ChangeLog yourself, do not rely on automatic tools (not all commit comments are useful).

The suggested style is described e.g. by GNU

Important is to have committer's name, and eventually patch author name and contact.

Significant changes in documentation are also important to log.

Bugzilla

If the change fixes a reported bug or implements a requested feature, always report revision number in which the problem is solved in Bugzilla.

Manuals and such

If the change implements a new feature or option, or changes usage in some other manner, update the corresponding LaTeX or HTML document.

Always follow Documentation writing guidelines.

man pages

If the component has man-pages, and if the change affects usage in some manner, always update the man page.

Configuration reference

If the change affects configuration options, update arc.conf.reference as well as corresponding user and administrator manuals.

Code documentation

Every piece of code must contain relevant comments:

In-line comments

In-line comments must be in English.

If non-ASCII characters need to be included in comments (e.g. in names), UTF-8 encoding must be used.

In-line comments must explain what the code is doing, to help other developers, especially newcomers.

In C++ code it is preferred to use "// a comment" notation rather than "/* a comment */".

Doxygen

Classes, public methods, enumerations, constants etc should be documented with doxygen-style comments. See here for how the generated documentation looks. Doxygen comments are mandatory for the API documentation. The suggested syntax is shown in the following example:

/// A class for doing something.
/**
 * This class does this and that
 * \headerfile MyClass.h arc/MyClass.h   <-- IMPORTANT for classes that are part of the API
 */
class MyClass {
 public:
  /// Make a new MyClass.
  MyClass();
  /// Change something.
  /**
   * Changes something into something else. 
   * \param thing the thing to change
   * \return true if change succeeded
   */
  bool ChangeSomething(Thing& thing);
};

Using other styles of doxygen syntax is acceptable as long as the generated documentation is consistent. At least a brief description must be present for all classes and methods of the ARC API. Note that the \headerfile command is required for these classes to show the correct include path in the generated documentation.