Coding Conventions

1. summary The bare essentials

Table of Contents Purpose Documentation Files Classes Class data members Class function members Functions Namespaces Names Increment Operators Code layout

Purpose

Coding conventions contribute to correctness, maintainability, software reuse and other measures of software quality. We have very few conventions or requirements but this makes those we have all the more important.

Documentation

We use Doxygen to automatically form our documentation from the commented program source.

Incorrect documentation is a bug and should be either fixed immediately or tracked as an issue for eventual fixing.

Most code documentation should appear in the header file so that people know where to look for it. However, on occasion it will be easier to maintain the documentation if it is next to the actual implementation.

Files

Near the top of every source file should be the doxygen comments to specify the name of the file and a one-line description of the contents. E.g., this from `tensor.h`.

/// \file tensor.h                                                                                                                    
/// \brief Declares and partially implements Tensor and SliceTensor.      

Without the `\file` the documentation in the file will not be extracted.

Classes

Precede each class definition (look here for definitions vs. declarations) with both a brief (one line) and a full description of the class. E.g.,

/// Specialization of Future for vector of Futures                                                                                

/// Enables passing a vector of futures into a task and having                                                                    
/// the dependencies correctly tracked.  Does not directly                                                                        
/// support most operations that other futures do ... that is                                                                     
/// the responsiblility of the individual futures in the vector.                                                                  
template <typename T>
class Future< std::vector< Future<T> > > : public DependencyInterface { ...

Class data members

Comment most of these at the point of definition as follows

bool compressed;  ///< True if function is compressed, false otherwise.

If the purpose of the variable is sufficiently clear (think of somebody else trying to extend/fix your code), or if the name is sufficiently descriptive there is no reason to add documentation.

Class function members

Comment all of these without exception with at least a single line brief description and as necessary with a full description. Anything other than set, get, or inquiry methods need to have a full description that contains a description of

1. each argument
2. the return value
3. side effects
4. associated interprocessor communication if relevant

Functions

As for class member functions.

Namespaces

In header files and library source files do not import any namespaces or symbols. Use the full names.

All MADNESS library functionality must be defined in the `madness` namespace.

Names

Pre-processor macros

Should be all uppercase with words separated by underscores. The first word should be the name of the containing software (e.g., `WORLD`, `MADNESS`, etc.).

Namespaces

Lowercase with words separated by underscores.

Class names

The first letter of each word should be capitalized and with no underscores

Class members (function and data)

All lower case with words separated by underscores

Functions

As for class member functions.

Increment Operators

You should prefer the prefix increment/decrement operations by default (unless you have a good reason to use the postfix version). This is because the postfix operator creates a copy of the incremented/decremented variable, while the prefix operator does not. This is especially important for iterators, which may be expensive to copy. Do NOT rely on the compiler to optimize away the copy when it is not needed.

Code layout

Code with whatever layout you find most comfortable. Infrequently, `astyle` will be run to impose a more uniform layout.