Coding Conventions

Hall-D Coding and Use Conventions

We have adopted a set of standards based on the CLEO coding conventions. You can find them here:

http://www.jlab.org/Hall-D/software/GlueXCodingStandard.html

Additional Policies

In addition to the conventions described in the document mentioned above, we have agreed on the following policies:

1. All code should compile and link without warnings on all supported platforms. Where that is impractical, this state should be clearly documented in the comments at the beginning of the code.
2. All random processes performed in smearing data between simulation and reconstruction should be placed in the mcsmear program and not in the reconstruction program. That way reconstruction results are reproducible on an event-by-event basis without having to keep track of random number seeds.

---

C++

• Classes specific to Hall-D/GlueX reconstruction will have names starting with the letter "D".

• Classes specific to a subsystem should include the subsystem name in the first part of the class name. For example, all classes in the CDC package should have names starting with "DCDC"

• The suffix for C++ source files should be .cc

• The suffix for C source files should be .c

• The suffix for both C++ and C header files should be .h

• The suffix .C will be used for ROOT macros and will therefore be ignored by the make system.

• The suffix for FORTRAN files should be .F

• The suffix .f will be used for PAW macros and will therefore be ignored by the make system.

• C++ source files will be named using the classname they provide.

• Multiple classes should be defined in a single header only under special circumstances.

• Classes should have a brief description of their purpose in a doxygen recognizable format(i.e. with three forwardslashes ///) inside the class definition in the header files.

• #include preprocessor directives should use double quotes for headers specific to Hall-D/GlueX code and angle brackets for all others. e.g.

 * #include <JANA/JEventLoop.h>
 * #include "DCDCHit.h"

• Factory classes derived from JFactory will have names that start with the data class (subclass of DObject) which they provide with "_factory" appended. For example:

DCDCHit_factory

• Tagged factory classes (factories with a tag other than an empty string) will have an underscore and the tag appended to the class name. For example, a factory with the tag "ALT1" :

DCDCHit_factory_ALT1

• Configuration Parameters in JANA should start with a common prefix and a colon to indicate the package where they are being implemented. For example, all configuration parameters implemented in the TRACKING package start with the prefix "TRK:" like this:

TRK:MAX_HIT_R_FDC

• Standard output should be directed to the "Dcout" stream rather than to the "cout" stream.

Header Files (files included by the pre-processor)

1. Content of all header files should be enclosed in a pre-processor #ifndef statement to prevent multiple inclusion. For example, a header file called "DMCTrackHit.h" should look like:

   #ifndef _DMCTRACKHIT_H_        /* check for definition (and thus inclusion) */
   #define _DMCTRACKHIT_H_        /* define it if not previously defined */
   
   #include <JANA/JObject.h>      /* start of actual header file content */
   using namespace jana;
   
   #include "GlueX.h"
   
   class DMCTrackHit:public JObject{
    public:
     JOBJECT_PUBLIC(DMCTrackHit);
   .
   .
   .
   #endif // _DMCTRACKHIT_H_      /* close definition-check if-block */
   

Standard Units

Unless explicity indicated otherwise, software will use the following standard units:

Quantity	Unit
length	centimeters
time	nanoseconds
energy	GeV
momentum	GeV/c
mass	GeV/c2
magnetic field	Tesla
electric potential	Volts
angles	radians