Home » Software & Computing » Infrastructure » Software Infrastructure » Software and Libraries

STAR coding and naming standards

Updated on Fri, 2015-10-30 09:47. Originally created by jeromel on 2007-08-18 17:20. Under:

STAR coding standards

  1. C++ programming Guidelines
  2. C++ coding style guidelines
  3. General STAR rules (FORtran and C coding style, STAR specific requirements)
  4. File extensions

STAR StRoot/ makers naming standards

  1. The directory structure under StRoot tree
  2. Trees and implicit/hidden rules
  3. Current patterned exceptions

STAR coding standards

Fortran and C coding style manual

postscript

STAR Specific requirements

The C++ coding guide should be consulted for the general standards and allowed/discouraged features in the SRA environment. In addition, the following information are provided
  • Hard-coded numbers within the code must be avoided for portability and maintainability reasons. The use of constants (const) is a valid solution. For values which are likely to change with time, a database approach should be considered. Refer to the database Web page area for more information.
  • For printing messages in the STAR framework use the StMessage message manager package documented here. For all messages from a given portion of code, use a unique string, like:
    { LOG_XXX << &quotStZdcVertexMaker::Init(): in ZdcVertexMaker did not find ZdcCalPars." << endm; }

    where XXX is either

    • DEBUG
    • INFO
    • WARN
    • ERROR
    • FATAL
    • QA

    Then, you can filter in/out the wanted / unwanted messages using the logger filter mechanism. The Logger documentation is available here and its use is encouraged.

  • To exit your code on an error condition in the STAR framework, return one of the STAR return codes (an enum) from your Maker: 
    enum EReturnCodes{
  kStOK=0,  // OK
  kStOk=0,  // OK
  kStWarn,  // Warning, something wrong but work can be continued
  kStEOF,  // End Of File
  kStErr,  // Error, drop this and go to the next event
  kStFatal      // Fatal error, processing impossible
};

    Outside Makers in your application code AND for testing or debugging  conditions that should never happen and indicate disaster if they do, we recommend the use of assert() (it aborts the program if the assertion is false). Don't use exit(). For info on assert() see the man page ('man assert').
    assert() should not be used in official code (apart from rare cases). Generally speaking, it is BAD practice to just abort the program and should be avoided. Better to message an error and propagate up a fatal error flag. Unless your Maker is a fundamental and base maker (DAQ detecting a corruption, db finding an unlikely condition which should really never happen, IO maker not able to stream, ...) the use of assert() is prohibited as a single detector sub-system error shall not lead to an entire chain abort. The use of clear messages with level FATAL is emphasized.

  • See also Class and method naming good advice

File Extensions

  • C++ header files containing ROOT related code must have the extension .h, the referring source files must have the extension .cxx. This rule is imposed on us by ROOT.

  • Plain C++ header files, i.e. those without ROOT related code have the extension .hh, the source files the extension .cc. Only header files which contains definitions usable in C and C++ may have the extension .h. This is a convention commonly used in HEP (e.g. CLHEP, Geant4).



STAR StRoot makers naming standards

This document attempts to explain

  • the code directory structure and layout in STAR

  • the rules and assumptions triggered in the make system (cons) solely on the basis of the name choice

  • the existing exceptions to the rules

Naming convention in green are user discouraged (proliferation prevention) and such request should be accompanied with a strong reasoning. Items in magenta are obsolete forms (and code) which will disappear and rendered obsolete in a near future. Anything appearing in red should be forgotten immediately as they are forbidden (and were introduced due to unfortunate momentary laps of reason, power surge or extreme special transitional needs).

Why a naming convention ??
Naming convention keeps consistency between code and packages written by many users. Not only it enables users to have a feel for what-does-what but also, it allows managers to define basic default set of compilation rules depending sometimes naming convention. Naming conventions in general are fundamental to all large projects and although N users will surely have N best-solution, the rules should be enforced as much as possible.

The directory structure under StRoot tree

The StRoot/ tree Is of the following form

StRoot/

XXX/

ONLY base class should be freely named. Example: StarClassLibrary, StarRoot, Star2Root

 

StXXX/

A directory tree which will contain a base class many makers will use and derive from.
In this category, XXX can be anything. For example, StChain, StEvent, StEventUtilities

 

St_XXX_Maker/

XXX not being a detector sub-system but a set of character with underscores:

the code is FORtran derived. XXX is a sub-system in a general sens (not necessarily a detector-sub-system)

 

StXXXMaker/

A tree for a Maker, that is, code compiled in this tree will be assembled as one self-sufficient package. A maker is a particular class deriving from StMaker. Its purpose is to run from within a chain (StChain) of makers and perform a specific task.

In this category, sub-name convention are as follow
* StXXXDbMaker a maker containing the database calls for the sub-system XXX (+)
* StXXXSimulationMaker or StXXXSimulatorMaker a simulation maker for the subsystem XXX
* StXXXCalibMaker or StXXXCalibrationMaker a calibration maker for the sub-system XXX
* StXXXMixerMaker a data/simulation mixer code for he sub-system XX
* StXXXDisplayMaker a self-explained named Graphical tool (+)
* StXXTagMaker a maker collecting tags for the sub-system or analysis XX

while XXX is in principle a detector sub-system identification (3 to 4 letters uniquely designating the sub-system), it may also be anything but a detector sub-system (StAssociationMaker, StMiniMcMaker, StDbMaker) or of the form XX=analysis or physics study.
 

StXXXRaw*/

Any directory with named with the word Raw will make our make system include the necessary path for the Run-Time-System DAQ reader files automatically. This convention is additive to any other description and convention herein.

Example: StEmcRawMaker is a "maker" 9as described above) and a code base using the DAQ reader and so would be the expectation for Stl3RawReaderMaker or StFgtRawMaker.

 

StXXXUtil/
StXXXUtilities/

Code compiled in a Util or Utilities tree should be code which do not perform any action (nor a maker) but constitute by itself a set of utility classes and functions. Other classes may depend on a Utility library.
* XXXUtil : XXX IS a sub-system detector.
* XXXUtilities : XXX IS NOT a detector sub-system (this is reserved)

 

StXXXPool/

This tree will contain a set of sub-directories chosen by the user, each sub-directory maybe a self-contained project with no relation with anything else. Each sub-directory will therefore lead to the creation of a separate library. The naming convention for the library creation is as follow :
* If the subdirectory is named like StYYY, the library will inherit the same name. Beware of potential name clash in this case
* If the subdirectory has an arbitrary name YYY, the final library name will be have the name StXXXPoolYYY .
The Pool category has some special compilation internal rules: if it does not compile, it may be removed from compilation entirely. As such, codes appearing in Pool directory trees cannot be part of a production maker dependency. A typical usage for this structure is to provide a Pool (or collection) of lose codes not used in production (utility tools for sub-systems, analysis codes or utilities).
XXX can be easer a Physics Work Group acronym or a detector sub-system acronym.

 

StXXXClient/

This tree will behave like the Pool trees in terms of library naming creation (separate libraries will be created, one per compilable sub-directory).
XXX can be anything relevant for a sub-system. Client directories MUST compile (unlike the pools) and may be part of a dependency of a data processing chain. Its general goal is to provide a different tree structure for a set of code providing a "service" widely used across makers. For example, the Run Time System (RTS) have a Client tree containing DAQ related reading codes.

 

Trees and implicit/hidden rules

StRoot/
StRoot/

StXXX./
(./)

README

A basic documentation in plain text (not mandatory). If exists, the software guide will display the information contained in this file.

 

 

doc/

A directory containing more elaborate documentation, either in html or in LaTeX. Note that if a file named index.html exists, the software guide will link to it

 

 

local/

A subdirectory containing stand-alone Makefiles for the package and/or standalone configuration files

 

 

examples/

A directory having a collection of code using the Maker or utility package of interest (case incensitive)

 

 

macros/

A directory containing root macros example making use of the maker

 

 

kumac/

This is an obsolete directory name (from staf time) but still considered by the make system. It may also appears in the pams/ tree structure.

 

 

test/

This directory may contain test programs (executables should in principle not appear in our standard but be assembled)

 

 

html/

A directory possibly containing cross-linked information for Web purposes. However, note that the documentation is, since 2002, auto-generated via the doxygen documentation system (see the sofi page for more information).

 

 

images/

A directory containing images such as bitmap, pixmaps or other images used by your program but NOT assembled by any part of the build process. XPM files necessary for Qt for example should not be placed in this directory as explicit rules exists in 'cons' to handle those (but cons will ignore the xpm placed in images/).
    wrk/
run/		  

 

 

include/

A directory containing a set of common include files

 

 

Any other name

Will be searched for code one level down only.
All compiled code will be assembled in one library named after to StXXX...
Each sub-directory will be compiled separately that is, each must contain code using explicit include path as the only default search paths for includes will be the one described by CPPPATH and its own directory. 1
Include statement can ALWAYS refer to the relative path after the StRoot/portion as the StRoot/ path is a default in CPPPATH.

 

StXXXPool/
StXXXClient/
(./)

doc/
local/
examples/
macros/
kumac/
test/
html/
images/
wrk/
run/
 include/

As noted above (i.e. the content of those directories will be skipped by the make system)

 

 

Any other name

The presence of every sub-directory will create a different dynamic library. Note that this is NOT the case with the other name format (all compiled code would go in a unique library name)
The convention is as follow:
* If the name starts with 'St', for example 'StZZZ', a library StZZZ.so will be created containing every compiled code available in StZZZ directory 2
* if the name does NOT start with 'St', for example 'WWW', a library StXXXPoolWWW.so will be created containing all compile code available in WWW directory

 

Current patterned exceptions.

 

StEventDisplay.*

Directories within this pattern will be compiled using the extra include path pointed by the environment variable QTDIR. The moc program will run on any include containing the Q_OBJECT directive, -DR__QT define is added to CXXFLAGS.

 

StDbLib
StDbBroker

Those are special. Compilation will consider MySQL includes and the created dynamic library will be linked against MySQL

 

St.*Db.*

Any directory following this pattern will use the MySQL include as an extra include path for the CPPPATH directive

 

StTrsMaker
StRTSClient

Are two exceptions of kind (b) [see footnote 1] and uses its own include/ directory as a general extraneous include path.

 

StHbtMaker

For this maker, a pre-defined list of sub-directories is being added to the (CPPPATH)

 

StAssociationMaker
StMuDSTMaker
.*EmcUtil
StEEmcPool
StTofPool
StRichPool
Sti.*

This form will include in the CPPPATH every sub-directories found one level below. Only macros/, examples/ and doc/ are excluded withing this form noted in (a). For the Pool directory, the extraneous rule mentioned here is additive to the one of Pool directories.



Direct comments to the STARSOFT list.

1However, if there is a need for StRoot/StXXX sub-directories compilation to include every available sub-paths (other than the exceptions noted above) (a) as a list of default path in a compiler option or if you want a default include/ directory (b) to be always added in a default include path compiler option statement, you may request this feature to be enabled. To do that, send an Email to STARSOFT .

2In this form, the sub-directory MUST be self-sufficient i.e. all code and include (apart from the default paths) must be in the sub-directory StZZZ

 

»