From NorduGrid

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

Contents 1 Naming 1.1 File names 2 Code layout 2.1 C++ template 2.2 if/while/for blocks 3 Printing output and error messages 4 Testing 5 Documenting 5.1 Every code change must be documented: 5.2 Every piece of code must contain relevant comments:

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

Every code change must be documented:

• In commit logs: provide all details. "Oops" or "reverting bad commit" are not valid commit log entries
  • If the change fixes a reported bug or implements a requested feature: always provide bug report (or feature request) number
• In Bugzilla: if the change fixes a reported bug or implements a requested feature, always provide revision number in which the problem is solved
• In the corresponding LaTeX or HTML document: if the change implements a new feature or option, or changes usage in some other manner
  • Always follow Documentation writing guidelines
• In man-pages: if the component has man-pages, and if the change affects usage in some manner
• In arc.conf.reference : if the change affects configuration options

Every piece of code must contain relevant comments:

• Standard comments interpretable by Doxygen, particularly the API documentation
• In-line comments helping other developers, especially newcomers