## HERD Offline Software Naming and Coding Conventions

### Definitions, of different naming conventions
see also <https://devopedia.org/naming-conventions>

- Camel Case:
   - name consists of meaningful words or abbrs,
   - the first letter of every word, but the first, is capitalized, with no spaces or symbols between words. 
   - Examples: `userAccount`, `fedEx`, `wordPerfect`.
   - in case the first word very short (1 letter), the second word starts with lowercase, e.g. `ibin`, `ntrack`, 
- Pascal Case:
   - like the Camel Case, but all the word starts with uppercase. 
   - Thus, `UserAccount` is in Pascal Case but not `userAccount`.
- Screaming Case: This refers to names in uppercase, with underscore between words.
   - Example: `TAX_RATE`.

### Package: Naming and Directory Conventions

- Package name: Pascal Case. e.g.: `DetectorSimulation` or `DetSim`
- Each package may include sub-directories: src, "_include_", python, scripts, compact, g4macro, ... 
- `CMakeList.txt` in the Package directory and defines all the building tools
- `<PackageName>/`: header files to be exported: `*.hh` (triditionally in `include` dir)
- `src/`: implementation files: `*.cc`
- `python/`: exported python package (for sniper): `*.py`
- `scripts/`: python scripts for running and testing
- `compact/`: DD4HEP compact detector descriptions, for detector geometry definition
- `g4macro/`: GEANT4 runtime macro files `*.g4mac`


### Coding Conventions 

#### Naming
- Namespaces: lower case, short
- Class names: Pascal Case, e.g. SimulationAlg
- Variables:
  - Data members are defined in the order of the type: public, protected and private.
  - Data members prefixed with m: `mEnergy`
  - Static variables begin with s: `sCount`
  - Constants begin with k or in Screaming Case: `kGainRatio`
  - Global variables begin with g: `gEnv`
- Functions:
   - function names: Camel Case: `setEnergy()`
   - [under discussion] getter/setter functions should correlate with variables: `mEnergy`/`setEnergy()`/`energy()`
      - if complex returning object, or complex calculation, the getter starts with `get`: `getDetectorDescription()`
      - for simple type, e.g. numbers, strings, three vectors, ... getter w/o "get" prefix: `energy()`, `position()`
   - Locals and parameters: Camel Case : `nbytes`,`recoEnergy`

#### Other
- Header files:
   - One header file usually for one class, except internal class definitions
   - Avoid duplication in header files:

         #pragma once
     or traditional include guard if you prefer:

         #ifndef NAMESPACE_CLASSNAME_H
         #define NAMESPACE_CLASSNAME_H
         ...
         #endif//NAMESPACE_CLASSNAME_H

   - Inline functions should be defined in the header files
   - Including external header files: `#include <package/header.h>`
   - Including local header files: `#include “header.h”`
- Indention (for C++ code):
   - use spaces, avoid tabs
   - *3 spaces for each level recommended*
   - *open braces `{` shall stand in it's own line, unless in `}else{` (recommended)*
- Data members should be initialized in the constructors of the class.

### Documentations in Comments
- Line comments starts with `// `
- Block comments:

      /**
       * ...
       */

    or

      /*
        ...
       */

- Each header file should have comments include the class definition, developer and e-mail.
- Each function member and data member should have line comments in definition
- Functions definitions shall have at least a brief introduction before them
- Try to follow the doxygen rules: <http://doxygen.nl/manual/docblocks.html>
- e.g.:

```
/**
 * Get the total energy based on calo cell hits.
 * 
 * @param algo select algorithm, 1=new, 0=old
 *
 */
double getTotalEnergy(int algo)
{
   // some calculation
}

```



### Read more

a further detailed guide (but slight different) can be found in FCCSW: <https://github.com/jlingema/FCCSW/blob/master/doc/CppCodingStyleGuidelines.md>