Coding guidelines

From MCRL2

File hierarchy

The following describes how libraries and tools should be organised in a file hierarchy.

Libraries

Organisation of libraries:

• A library named foo is located in the directory libraries/foo.
• Each library directory has the following directory structure:

• Include files belonging to library foo must be placed in the directory include/mcrl2/foo. Optionally a header file include/mcrl2/foo/foo.h may be added, that contains include directives for the most commonly used header files in include/mcrl2/foo.
• Library code is put in the namespace mcrl2. If needed, a library foo can use it's own namespace mcrl2::foo.

Tools

Organisation of tools:

• A tool named foo is located in the directory tools/foo.
• Each tool directory has the following directory structure:

• Build files, source files and include files are located in the tool directory itself.
• Reusable code must be put in a library, not in a tool!

Note: some of these guidelines were taken from [1].

Programming

Except for third party software, every header and source file should adhere to following guidelines.

Preamble

Every file should start with a preamble containing author names and links to copying and license information. The preamble should be formatted as follows, where AUTHORS stands for the names of the authors:

// Author(s): AUTHORS
//
// Copyright: see the accompanying file COPYING or copy at
// https://svn.win.tue.nl/trac/MCRL2/browser/trunk/COPYING
//
// Distributed under the Boost Software License, Version 1.0.
// (See accompanying file LICENSE_1_0.txt or copy at
// http://www.boost.org/LICENSE_1_0.txt)

Naming conventions

The following naming conventions regarding filenames should be used:

• Filenames should be all lowercase.
• The following file extensions should be used:
  • .cpp for source files;
  • .h for header files.

The following naming conventions regarding file contents should be used:

• Use the naming conventions of the C++ Standard Library.
• Names (except as noted below) should be all lowercase, with words separated by underscores.
• Template parameter names begin with an uppercase letter.
• Macro names all uppercase and begin with MCRL2_.
• Choose meaningful names - explicit is better than implicit, and readability counts. There is a strong preference for clear and descriptive names, even if lengthy.

Header policy

The following guidelines are specific to header files (based on [2]):

• Unless multiple inclusion is intended, wrap the header in #ifndef guards.
• Wrap the header contents in a namespace to prevent global namespace pollution. mCRL2 libraries should be placed in the namespace mcrl2.
• Make sure that a translation unit consisting of just the contents of the header file will compile successfully. In other words, a source file with content #include "foo.h" should compile for every header file foo.h.
• Place the header file in a sub-directory to prevent conflict with identically named header files in other libraries.
• To avoid namespace pollution, the use of the using and using namespace directives is not allowed at the global parts of the header.

The following is a sample header:

// Author(s): AUTHORS
//
// Copyright: see the accompanying file COPYING or copy at
// https://svn.win.tue.nl/trac/MCRL2/browser/trunk/COPYING
//
// Distributed under the Boost Software License, Version 1.0.
// (See accompanying file LICENSE_1_0.txt or copy at
// http://www.boost.org/LICENSE_1_0.txt)
//
/// \file FILE_NAME
/// \brief BRIEF_DESCRIPTION
 
#ifndef MCRL2_MY_CLASS_H
#define MCRL2_MY_CLASS_H
 
namespace mcrl2 {
 
  class my_class
  {
    public: 
      void f();
    private:
      int x;
  };
 
} // namespace
 
#endif  // MCRL2_MY_CLASS_H

Exception handling

Use exceptions to report errors where appropriate, and write code that is safe in the face of exceptions.

Standards compliance

Aim for ISO Standard C++. That means making effective use of the standard features of the language, and avoiding non-standard compiler extensions. It also means using the C++ Standard Library where applicable.

Regression tests

Provide a regression test program or programs.

Usability

Provide sample programs or confidence tests so potential users can see how to use your library.

Platform independence

The source code must compile on the actively supported platforms and supported build tools on those platforms.

Committing changes

When committing changes, the following guidelines should be adhered to:

• Make sure the updated code successfully compiles, installs, and passes all tests.
• Enter a clear commit message.
• Whenever a commit solves a Trac ticket, the following steps should be performed:
  1. Commit the changes and in the commit message refer to the ticket by its number, formatted as #<n>, where <n> represents the ticket number.
  2. Close the ticket and enter a text comment indicating which svn revision resolves the ticket, formatted as r<n>, where <n> represents the revision number.