Naming¶

This section contains guidelines on how to name objects in a program.

Naming of files¶

Each class should have one header file, ending with “.h”, and one implementation file, ending with “.cxx”. [source-naming]

Some exceptions: Small classes used as helpers for another class should generally not go in their own file, but should instead be placed with the larger class. Sometimes several very closely related classes may be grouped together in a single file; in that case, the files should be named after whichever is the “primary” class. A number of related small helper classes (not associated with a particular larger class) may be grouped together in a single file, which should be given a descriptive name. An example of the latter could be a set of classes used as exceptions for a package.

For classes in a namespace, the namespace should not be included in the file name. For example, the header for Trk::Track should be called Track.h.

Implementation (“.cxx”) files that would be empty may be omitted.

The use of the “.h” suffix for headers is long-standing ATLAS practice; however, it is unfortunate since language-sensitive editors may then default to using “C” rather than “C++” mode for these files. For Emacs, it can help to put a line like this at the start of the file:
```
// This file is really -*- C++ -*-.
```

Meaningful names¶

Choose names based on pronounceable English words, common abbreviations, or acronyms widely used in the experiment, except for loop iteration variables. [use-meaningful-names]

For example, nameLength is better than nLn.

Use names that are English and self-descriptive. Abbreviations and/or acronyms used should be of common use within the community.
Do not create very similar names. [no-similar-names]

In particular, avoid names that differ only in case. For example, track / Track; c1 / cl; XO / X0.

Required naming conventions:¶

Generally speaking, you should try to match the conventions used by whatever package you’re working on. But please try to always follow these rules:

Use only ASCII characters in identifier names [ascii-identifiers]

This is what C++ calls the basic character set. Specifically, identifiers should use only the characters a-z, A-Z, 0-9, and underscore.

Handling of non-ASCII characters is implementation-defined. While many compilers can indeed handle extended (unicode) characters, not all tools may process them correctly. Some characters may not display correctly, depending on a user’s local installation. Further, it is often not obvious how to type an arbitrary unicode character that one sees displayed, especially since there exist distinct characters that look very similar or identical.
Use prefix m_ for private/protected data members of classes. [data-member-naming]

Use a lowercase letter after the prefix m_.

An exception for this is xAOD data classes, where the member names are exposed via ROOT for analysis.
Do not start any other names with m_. [m-prefix-reserved]
Do not start names with an underscore. Do not use names that contain anywhere a double underscore. [system-reserved-names]

Such names are reserved for the use of the compiler and system libraries.

The precise rule is that names that contain a double underscore or which start with an underscore followed by an uppercase letter are reserved anywhere, and all other names starting with an underscore are reserved in the global namespace. However, it’s good practice to just avoid all names starting with an underscore. An exception is the use of a single underscore to indicate something that’s structurally required but ignored.

Recommended naming conventions¶

If there is no already-established naming convention for the package you’re working on, the following guidelines are recommended as being generally consistent with ATLAS usage.

Use prefix s_ for private/protected static data members of classes. [static-members]

Use a lowercase letter after the prefix s_.
The choice of namespace names should be agreed to by the communities concerned. [namespace-naming]

Don’t proliferate namespaces. If the community developing the code has a namespace defined already, use it rather than defining a new one. Examples include Trk:: for tracking and InDet:: for inner detector.
Use namespaces to avoid name conflicts between classes. [use-namespaces]

A name clash occurs when a name is defined in more than one place. For example, two different class libraries could give two different classes the same name. If you try to use many class libraries at the same time, there is a fair chance that you will be unable to compile and link the program because of name clashes. To solve the problem you can use a namespace.

New code should preferably be put in a namespace, unless typical ATLAS usage is otherwise. For example, ATLAS classes related to the calorimeter conventionally start with “Calo” rather than being in a C++ namespace.
Start class and enumeration types with an uppercase letter. [class-naming]
```
class Track;
enum State { green, yellow, red };
```
Type alias (typedef) names should start with an uppercase letter if they are public and treated as classes. [typedef-naming]
```
using TrackVector =
  std::vector<MCParticleKinematics*>;
```
Alternatively, a type alias (typedef) name may start with a lower-case letter and end with _t. [typedef-naming-2]

This form should be reserved for type names which are not treated as classes (e.g., a name for a fundamental type) or names which are private to a class.
```
using mycounter_t = unsigned int;
```
Start names of variables, members, and functions with a lowercase letter. [variable-and-function-naming]
```
double energy;
void extrapolate();
```
Names starting with s_ and m_ should have a lowercase letter following the underscore.

Exceptions may be made for the case where the name is following standard physics or mathematical notation that would require an uppercase letter; for example, uppercase E for energy.
In names that consist of more than one word, write the words together, and start each word that follows the first one with an uppercase letter. [compound-names]
```
class OuterTrackerDigit;
double depositedEnergy;
void findTrack();
```
Some ATLAS packages also use the convention that names are entirely lowercase and separated by underscores. When modifying an existing package, you should try to be consistent with the existing naming convention.
All package names in the release must be unique, independent of the package’s location in the hierarchy. [unique-package-names]

If there is a package, say “A/B/C”, already existing, another package may not have the name “D/E/C” because that “C” has already been used. This is required for proper functioning of the build system.
Underscores should be avoided in package names. [no-underscores-in-package-names]

The old ATLAS rule was that a _ should be used in package names when they are composites of one or more acronyms, e.g. TRT_Tracker, AtlasDB_*. Underscores should be avoided unless they really help with readability and help in avoiding spelling mistakes. TRTTracker looks odd because of the double “T”. Using underscores in package names will also add to confusion in the multiple-inclusion protection lines.
Acronyms should be written as all uppercase. [uppercase-acronyms]
```
METReconstruction, not MetReconstruction
MuonCSCValidation, not MuonCscValidation
```
Unfortunately, existing code widely uses both forms.