ALICE O² C++ Comments Guidelines

Hooray! Now you know you can expand points to get more details. Alternatively, there's an "expand all" at the top of this document.

Doxygen uses structural commands that start with a backslash \ and indicate what you are documenting. Examples are: \class to document a class, \namespace to document namespaces and so on.

It has other complex funcionality such as including formulas, graphs, diagrams and much more. Below we give just a few useful tips how to structure the text in the comments to get it properly formatted in the Web documentation.

• To make a list:

  /// - item1
  /// - item2

• To make a numbered list:

  /// -# item1
  /// -# item2

• To keep the text layout place the text in between the lines (mainly when the text represent a sample of code, macro or command lines typed in terminal):

  /// \verbatim
  /// ...
  /// \endverbatim

For more details on how to use Doxygen, go to Doxygen manual.

The /* */ does not allow nested comments that's why we prefer to limit its usage only in cases when no other way is possible.

For example to avoid warnings about unused arguments we can better place them within /* */ comments:

void print(const std::string& /*option*/) {
  // ...
}  

void print(const std::string&) {    
  // ...
}  

Comments should be as readable as narrative text, with proper capitalization and punctuation. In many cases, complete sentences are more readable than sentence fragments. Shorter comments, such as comments at the end of a line of code, can sometimes be less formal, but you should be consistent with your style.

Although it can be frustrating to have a code reviewer point out that you are using a comma when you should be using a semicolon, it is very important that source code maintain a high level of clarity and readability. Proper punctuation, spelling, and grammar help with that goal.

Example:

inline void FitC::Filter(Track &track, const HitInfo &measurementModel,
    const float_v m, const float_v weight) const
{
  const float_v sigma2   = measurementModel.sigma2;
  const float_v sigma216 = measurementModel.sigma216;
  const Matrix<float_v, 5> F = track.C.slice<0, 5, 0, 2>()
                             * measurementModel.transposed(); //  CHᵀ
  const float_v HCH = measurementModel * F.slice<0, 2>();     // HCHᵀ
  const float_v residual = measurementModel
                         * track.slice<0, 2>() - m;   // ζ  = Hr - m
  float_v denominator = HCH;
  denominator(HCH < sigma216) += sigma2;
  const float_v zetawi = residual / denominator;      // (V + HCHᵀ)⁻¹ ζ
  track -= F * zetawi;                       // r -= CHᵀ (V + HCHᵀ)⁻¹ ζ
  track.C -= F * (weight / (sigma2 + HCH))* F.transposed();
                                             // C -= CHᵀ (V + HCHᵀ)⁻¹ HC
  track.Chi2(HCH < sigma216) += residual * zetawi;
                                              // χ² += ζ (V + HCHᵀ)⁻¹ ζ
  track.NDF += weight;
}

Legal Notice and Author Line

Every file should contain the copyright and license boilerplate:

// Copyright CERN and copyright holders of ALICE O2. This software is
// distributed under the terms of the GNU General Public License v3 (GPL
// Version 3), copied verbatim in the file "COPYING".
//
// See http://alice-o2.web.cern.ch/license for full licensing information.
//
// In applying this license CERN does not waive the privileges and immunities
// granted to it by virtue of its status as an Intergovernmental Organization
// or submit itself to any jurisdiction.

The license boilerplate should be followed by the author line, containing the full name of the authors and their affiliation(s). If you make significant changes to a file with an author line, consider replacement of the author line with yours.

File Contents

Every file should have a comment at the top describing its contents.

Generally a file description just refers to the class which is declared or implemented in the file. More detailed information about the implementation should go in the class description.

For class definition files:

/// \file MyClass.h
/// \brief Definition of the MyClass class.
///
/// \author John Brown, Institute XYZ

For class implementation files:

/// \file MyClass.cxx
/// \brief Implementation of the MyClass class.
///
/// \author John Brown, Institute XYZ

If the comment spans on more than one line put a summary line first separated from the detailed description with an empty comment line.

/// Short MyClass description
///
/// More detailed MyClass description
/// which can span on more lines

class MyClass 
{
  ...
};

Function Declarations

Every function declaration should have comments immediately preceding it that describe what the function does and how to use it. These comments should be descriptive ("Opens the file") rather than imperative ("Open the file").

The Doxygen keywords \param and \return can be used to describe the function arguments and the return value. Note that when using these keywords, all arguments have to be documented.

Here is an example:

/// Opens a file.
/// \param name  The name of a file to open
/// \return      Return true if open successfully.
bool OpenFile(const std::string& name);

Do not skip comments even for trivial functions like constructors and destructors, even though everyone reading your code knows what constructors and destructors are for, but put a standard agreed text:

/// Default constructor
MyClass();
/// Standard constructor
MyClass(int value);
/// Destructor
~MyClass(int value);
/// Disabled constructor
MyClass() = delete;
/// Disabled destructor
~MyClass(int value) = delete;

This will allow to automatise checking for functions with no comments provided.

Function Definitions

Function definitions can also have a comment describing what the function does if there's anything tricky about how it does its job.

Note you should not just repeat the comments given with the function declaration, in the .h file.

/// More details can be given to a function definition in .cxx file
bool MyClass::OpenFile(const std::string& name);

Short comments can be placed after the data member definition. They have to be preceded with ///< unless a special syntax is required by the external packages. For example:

private:
  int mTotalNumberOfEntries; ///< Total number of entries

Long comments should be placed before the data member definition. For example:

private:
  /// Keeps track of the total number of entries in the table.
  int mTotalNumberOfEntries;

If the comment spans on more than one line put a summary line first separated from the detailed description with an empty comment line. For example:

private:
  /// Keeps track of the total number of entries in the table.
  ///
  /// Used to ensure we do not go over the limit. -1 means
  /// that we don't yet know how many entries the table has.
  int mTotalNumberOfEntries;

In special cases, when a given syntax is required by an external package, another form of the comment, compliant with Doxygen rules, should be used. In classes using ROOT IO, use //!< for the data members excluded from IO. For example:

private:
  int    mTotalNumberOfEntries; ///< Total number of entries
  double mBuffer;               //!< Temporary buffer

If the comment spans on more than one line put a summary line first separated from the detailed description with an empty comment line.

/// Short MyNamespace description
///
/// More detailed MyNamespace description
/// which can span on more lines

namespace MyNamespace 
{
  ...
}

Example:

/// Enumeration for possible application states.
enum ApplicationState {
  ApplPreInit,          ///< application is not yet initalized
  ApplIdle,             ///< application is ready for event processing
  ApplEventProcessing,  ///< application is processing events
  ApplAbort,            ///< application is aborted
  ApplExit              ///< application is exiting
};

Complex Code Blocks/Lines

Tricky or complicated code blocks can have comments before them. Note that such comments should be preceded with //, as they are not supposed to go to the Web documentation. Example:

// Divide result by two, taking into account that x
// contains the carry from the add.
for (int i = 0; i < result->size(); i++) {
  x = (x << 8) + (*result)[i];
  (*result)[i] = x >> 1;
  x &= 1;
}

Also, lines that are non-obvious can get a comment at the end of the line. These end-of-line comments should be separated from the code by 2 spaces. Example:

// If we have enough memory, mmap the data portion too.
mmapBudget = max<int64>(0, mmapBudget - index_->length());
if (mmapBudget >= mDataSize && !MmapData(mmapChunkBytes, mlock))
  return;  // Error already logged.

Note that there are both comments that describe what the code is doing, and comments that mention that an error has already been logged when the function returns.

If you have several comments on subsequent lines, it can often be more readable to line them up:

doSomething();                  // Comment here so the comments line up.
doSomethingElseThatIsLonger();  // Comment here so there are two spaces between
                                // the code and the comment.

To Do Comments

Precede comments with \todo keyword for code that is temporary, a short-term solution, or good-enough but not perfect. A list of these items will be then automatically included in the generated Web documentation.

/// \todo Use a "*" here for concatenation operator.
/// \todo Zeke change this to use relations.

If your comment is of the form "At a future date do something" make sure that you either include a very specific date ("Fix by November 2005") or a very specific event ("Remove this code when all clients can handle XML responses.").