STAR   Computing


STAR Coding and naming Standards



STAR coding standards

  1. C++programming Guidelines
  2. C++ coding style guidelines
  3. File extensions
  4. Miscellaneous

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

HTML, postscript

C++ Programming Guidelines

The programming guidelines refer to how programming language features are used. They have to do with things like adhesion to object oriented programming (data-hiding, encapsulation, etc ...), performance and portability.

C++ coding style guidelines

The coding-style guidelines are the ones which refer to the editing styles of the source code. They have to do with things like the code maintainability and readability (see motivations).

File Extensions


Good advice on naming

These guidelines originated with the members of the STAR online group and the TpcRespSim project. Many of them were taken from the guidelines of the Geant4 project. Direct comments to the STARSOFI list.

STAR StRoot makers naming standards

This document attempts to explain

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 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



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


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


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)


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.


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)


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)
XXX can be easer a Physics Work Group acronym or a detector sub-system acronym


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).

Trees and implicit/hidden rules




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


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


A subdirectory containing stand-alone Makefiles for the package.


A directory having a collection of code using the Maker or utility package of interest


A directory containing root macros example making use of the maker


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.


This directory may contain test programs


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).




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.



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 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 will be created containing all compile code available in WWW directory

Current patterned exceptions.


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.


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


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


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


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


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 STARSOFI 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 STARSOFI .

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