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