Scope of Guidelines

The HadronZoo coding standards guidelines are intended to apply to all C++ code, be it for for internal use, for delivery to clients or for publication on the HadronZoo website. It is acknowleged however, that some of the code in the current code base does not fully comply with the standards. This is mainly due to code predating standards. There is an ongoing effort to rectify this.

The code acceptance and publication process is partly automated. HadronZoo::CodeProc is a psudo complier and document assembly program that examines a C++ code body, identifies key items of interest (e.g. classes and member functions), from which it compiles a technical manual suitable for online publication. CodeProc is not a comprehensive enforcer of coding standards, but it does enforce the standards with regards to comments - as these are the principle source of text for the manual pages. In order to be accepted into the code base, all new and changed code must be processed by the CodeProc program.

Class Groupings

The code demarcation is group centric first, class centric second. Classes that stand alone e.g. hzString and hzChain, are defined in a single dedicated header file and implimented in a single source file - as would generally be expected. However where classes naturally form a related group, the recommendation is that all classes in the group are defined in a single large header. Implimentation can be likewise, except that volume will likely favor a split, which is best done along class lines.

Header File and Class Definition Layout

All header (and source) files should begin with an opening comment block, stating file name, author, date, version and any applicable legal notice. The broad intention is for there to be tracable history in the author, date and version fields. However in the current HadronZoo code body, only the latest date and version is supplied.

The next part of the header file is the compulsory 'inclusion control' compiler directive of the form:- <pre> #ifndef basename_h #define basename_h </pre>

Where 'basename' is the name of the header file minus the '.h' This avoids recursive inclusion and is compulsory even where recursive inclusion would not occur. Note this directive means the file must have a terminating #endif but this does not come until the very end of the header file.

There then follows the list of #includes if any. Ideally these should be kept purged to a minimum. Always consider using forward declarations of classes upon which the class(es) in the header depend.

Next should be a comment block explanating of the purpose and methodology of the class or where applicable, set of classes. This can refer to a separately written synopsis.

Next are definitions of anything the class(es) will need that are not defined in any other header file, such as enumerations and #defines. Note that the latter are sometimes better declared in .cpp files as const variables in which case they can be declared extern in this header.

Layout of Class Definition Body

All classes should have a comment block describing the class in some detail. This should appear either directly before the class definition body or directly after the opening curly brace. If the former the comment block must begin with a line of the form 'Class: class_name' as this tells autodoc to associate the comment block with the class.

The components of the class begin with the private members. First the variables if any, followed by private method declarations, if any. Next comes the similarly ordered protected section, if applicable. The public section comes last, again with variables first and then methods. The public methods are grouped and appear in the following order: Constructors, descructors, initialization methods (if any), very small 'Get() and Set()' type inlines (if any), then mainstream methods, then static methods if any, and lastly friend methods.

There is a school of thought that favors placing the public methods of a class first so that they are near the top and save developers time when looking them up. We don't agree. It implies class definition are not riveting enough to read all the way though!

All class variables declarations should be followed by a line comment (opened with a //). If nessesary the comment will span multiple lines and where it does, each line must begin with the // directly underneath that of the first line, forming a comment block. CodeEnforcer only looks for descriptions of variables at this juncture. Uncommented variables show up in the gererated output as having 'No Description'. There is a similar rule for function arguments but only when functions are separately defined in a .cpp file.

This brings us to the question of what instruction code if any, should be allowed in header files. Some coding standards insist that no instructions whatsoever should appear in the headers, and that it should be placed in the source file and marked inline. HadronZoo considers this too strict and simply bans 'meaningful functionality' from function definitions in header file. If the function does nothing more than assign or return a value, the function body can go in the header. The function body must go in the source file if it contains variable declarations, instructions that allocate memory, or tests anything other than member variables.

Note that in all cases the default constructor should stick strictly to constructing a BLANK instance of the class, while the copy constructor if applicable, should stick strictly to constructing an instance that is a copy.

After the class definition(s) the header will contain extern declarations to any global variables that are declared in the dependant .cpp file(s). Then finally, will be the prototypes of any related non-member methods that appear in the dependant .cpp file(s).

Source File Layout

All source files begin with the same compulsory opening comment block used in header files. This is followed by the list of applicable #includes with the standard template includes such as <iostream>, listed first. System includes such as <unistd.h> next and finally the HadronZoo includes. When used, the "using namespace std" directive, ususally comes last.

The #include directives are followed by an introductory comment block which like header files, can be a synopsis. More commonly, the synopsis is in the header and the introductory block in a source file will contain notes specific to implementation. The introductory comment block can simply be a reference to a synopsis in the header, for example "This file implements the such and such class as defined in suchandsuch.h"

The next section will be local definitions, if any apply. After that comes the varibable declaration section. Global variables come first, followed by variables static to the file. There is a general covention of declaring variables in descending order of size, but also with class instances taking precedence over class instance pointers. Numeric entities are last.

The final section of the source file will be the functions themselves.