Naming conventions in general

Naming conventions are a core part of any coding standards policy. All C++ entities should have names that are inherently descriptive however an over-zealous approach to this is an easy mistake to make. While the dangers of brevity are obvious, descriptive precision can lengthen object names to unweildy proportions and this in itself, becomes an impediment to clarity. This is a very common trap. Inherent in the term 'dyslexia', is the notion that one is either dyslexic or one is not. In fact lexical skills are more of a grey scale, with many programmers being rather worse at this than they dare to suppose!

HadronZoo considers the most effective naming conventions are those that consistantly apply two particular inconsistancies! One is size, the other is specifics. Names should either be long or short and either be very specific or very generic! This is not a hard and fast rule, just something that helps the name stand out. The name of any entity, particularly a class or function, should be done on the functionality - but then be abrieviated.

Naming conventions for header and source files

In cases where a set of related classes form a module, the header should be named after the module. This would also be true of a single source file although in cases where module implimentation spaned multiple source files, this would depend on the module divisions. Where headers and sources are centered on a single class or at least a single dominant class then they should be called 'classname.h' and 'classname.cpp'. In both cases the class/file names will begin with the library or application prefix.

Class Names

Most classes are of global scope and are defined in header files. Where this is the case, the core of the name should be a single word or a pair of words. The words will begin with an upper case letter, and there must be no underscores. Then the core of the name is prefixed with a lower case sequence denoting an associated project. Note that in the HadronZoo library, classes are prefixed with 'hz', except for the Dissemino classes that are prefixed with 'hzw' and the HDB classes that are prefixed with 'hdb'.

Classes that are created for purely internal use should be defined in the source file that uses them. It is accepted that this is not always precticle as the source using the class may span multiple source files. Internal classes follow a different naming convention. Again names should reflect the functionality but the name will start with an underscore (this marks the class as internal), have words in all lower case and separated by undescores.

Function Names

For global or public functions, the name should contain no underscores and be a single word or a pair of words, begining with an upper case letter. Function names must describe the action of the function but should not exceed 20 characters. This is not a hard and fast rule but as names approach this size then the need for an accurate description of the action must give way to brevity. Fuction names do not carry the project prefix. Internal functions follow the same convention as internal classes. The names reflect the functionality but start with an underscore, all words in lower case and separated by undescores.

Note that that any function, internal or otherwise, is postfixed by '_r' if it is expected to be called recursively.

Standard Variable Names

The first part of a non member or class member variable name is a single lower case letter followed by an underscore. The letter indicates the scope. 'g_' indicates the variable is global, 's_' indicates the variable is static (within a file) and 'm_' indicates the variable is a class member. Automatic variables, whose scope is the function body in which they are declared, omit the scope indicator.

The next part is one or more lower case letters. This will be a single 'p' if the variable is a pointer but otherwise the letters indicates the approximate type as follows:- <pre> 'arr' - Array, either a hzArray or a C++ array. 'vec' - hzVect (another form of array). 'map' - Map, 1:1 or 1:many. 'set' - Set. 'b' - boolean. 'c' - a fixed length charachter array. 'e' - an enumeration. 'f' - floting point number (either a float or a double). 'n' - integer (either a byte, short, long or longlong, signed or unsigned). 'l' - generic linked list. </pre>

The final part is the name proper. As for functions, names must be capitalised, and underscores should not be used. Again there is the same playoff between accurate description and brevity.

Iterators and Loop Control Variable Names

Iterators and loop control variables should have very short names such as 'i', 'j' or 'k' - to mark them out as iterators and loop control variables. However, such variables SHOULD NOT be used outside the loop.

Constants and #define Names

Put all #define constants in upper case. This makes it very clear that the value is a constant. Ditto for declared constants. #defines and constants tend to either be standalone or belong to a family of values. Where the value is standalone make it one joined up word, for example:-

<pre class="codefrag"> #define BLOCKSIZE 4096 </pre>

In the case of a family of values use two sections. Put the family first and the value name proper last and separate with an underscore, for example:- <pre class="codefrag"> #define FILE_NOEXIST 1001 #define FILE_NOPERM 1002 </pre>