Style¶

This section concerns the style, as opposed to the functionality, of the code.

General aspects of style¶

The public, protected, and private sections of a class must be declared in that order. Within each section, nested types (e.g. enum or class) must appear at the top. [class-section-ordering]

The public part should be most interesting to the user of the class, and should therefore come first. The private part should be of no interest to the user and should therefore be listed last in the class declaration.
```
class Path
{
public:
  Path();
  ~Path();

protected:
  void draw();

private:
  class Internal {
    // Path::Internal declarations go here ...
  };
};
```
Keep the ordering of methods in the header file and in the source files identical. [method-ordering]

This makes it easier to go back and forth between the declarations and the definitions.
Statements should not exceed 100 characters (excluding leading spaces). If possible, break long statements up into multiple ones. [long-statements]
Limit line length to 120 character positions (including white space and expanded tabs). [long-lines]
Include meaningful dummy argument names in function declarations. Any dummy argument names used in function declarations must be the same as in the definition. [dummy-argument-names]

Although they are not compulsory, dummy arguments make the class interface much easier to read and understand.

For example, the constructor below takes two Number arguments, but what are they?
```
class Point
{
public:
  Point (Number, Number);
};
```
The following is clearer because the meaning of the parameters is given explicitly.
```
class Point
{
public:
  Point (Number x, Number y);
};
```
The code should be properly indented for readability reasons. [indenting]

The amount of indentation is hard to regulate. If a recommendation were to be given then two to four spaces seem reasonable since it guides the eye well, without running out of space in a line too soon. The important thing is that if one is modifying someone else’s code, the indentation style of the original code should be adopted.

It is strongly recommended to use an editor that automatically indents code for you.

Whatever style is used, if the structure of a function is not immediately visually apparent, that should be a cue that that function is too complicated and should probably broken up into smaller functions.
Do not use spaces in front of [] and to either side of . and ->. [spaces]
```
a->foo()  // Good
x[1]      // Good
b . bar() // Bad
```
Spacing in function calls is more a matter of taste. Several styles can be distinguished. First, not using spaces around the parentheses (K&R, Linux kernel):
```
foo()
foo(1)
foo(1, 2, 3)
```
Second, always putting a space before the opening parenthesis (GNU):
```
foo ()
foo (1)
foo (1, 2, 3)
```
Third, putting a space before the opening parenthesis unless there are no arguments.
```
foo()
foo (1)
foo (1, 2, 3)
```
Fourth, putting spaces around the argument list:
```
foo()
foo( 1 )
foo( 1, 2, 3 )
```
In any case, if there are multiple arguments, they should have a space between them, as above. A parenthesis following a C++ control keyword with as if, for, while, and switch should always have a space before it.
Keep the style of each file consistent within itself. [style-consistency]

Although standard appearance among ATLAS source files is desirable, when you modify a file, code in the style that already exists in that file. This means, leave things as you find them. Do not take a non-compliant file and adjust a portion of it that you work on. Either fix the whole thing, or code to match.
Prefer using to typedef. [prefer-using]

To declare a type alias, prefer the newer using syntax:
```
using Int_t = int;
```
to the typedef syntax:
```
typedef int Int_t;
```
The using syntax makes it clearer what is being defined; it can also be used to declare templated aliases.

Comments¶

Use Doxygen style comments before class/method/data member declarations. Use “//” for comments in method bodies. [doxygen-comments]

ATLAS has adopted the Doxygen code documentation tool, which requires a specific format for comments. Doxygen comments either be in a block delimited by /** */ or in lines starting with ///. We recommend using the first form for files, classes, and functions/methods, and the second for data members.

/**
 * @file MyPackage/MyClusterer.h
 * @author J. R. Programmer
 * @date April 2014
 * @brief Tool to cluster particles.
 */

#ifndef MYPACKAGE_MYCLUSTERER_H
#define MYPACKAGE_MYCLUSTERER_H


#include "MyPackage/ClusterContainer.h"
#include "xAODBase/IParticleContainer.h"
#include "AthenaBaseComps/AthAlgTool.h"


namespace MyStuff {


/**
 * @brief Tool to cluster particles.
 *
 * This tool forms clusters using the method
 * described in ...
 */
class MyClusterer
{
public:
  ...

  /**
   * @brief Cluster particles.
   * @param particles List of particles to cluster.
   * @param[out] clusters Resulting cluster list.
   *
   * Some additional description can go here.
   */
  StatusCode
  cluster (const xAOD::IParticleContainer& particles,
           ClusterContainer& clusters) const;

  ...

private:
  /// Property: Cluster size.
  float m_clusterSize;

  ...
};


} // namespace MyStuff


#endif // MYPACKAGE_MYCLUSTERER_H

See the ATLAS Doxygen page [18].

Remember that the /* */ style of comment does not nest. If you want to comment out a block of code, using #if 0 / #endif is safer than using comments.

All comments should be written in complete (short and expressive) English sentences. [english-comments]

The quality of the comments is an important factor for the understanding of the code. Please do fix typos, misspellings, grammar errors, and the like in comments when you see them.

In the header file, provide a comment describing the use of a declared function and attributes, if this is not completely obvious from its name. [comment-functions]

class Point
{
public:
  /**
   * @brief Return the perpendicular distance
   *        of the point from Line @c l.
   */
  Number distance (Line l);
};

The comment includes the fact that it is the perpendicular distance.