Rules

1. Place a unique and predictable internal include guard around the contents of each header file.
   • Style suggestion: For Trybos_AbstractRecord.hh use:
     

              #ifndef _Trybos_AbstractRecord_hh_
              #define _Trybos_AbstractRecord_hh_
              // All of Trybos_AbstractRecord.hh here
              #endif

2. The following rule may be useful if preprocessor efficiency is a concern:
   Place a redundant external include guard around each preprocessor include directive in each header file.
   • This will stop the preprocessor from even opening a file if the file has already been included.
   • Example:
     

             #ifndef  _Trybos_Package_hh_
             #include "Trybos_Package.hh"
             #endif

3. The .cc file of every component should include the corresponding .hh file as the first substantive line of code.
   • Ensures that the .hh file parses by itself, and another user would not have to figure out what other header files to include before the .hh file (the .hh file should include them itself).
   
   
4. Prepend every global identifier with its package prefix.
   • For example: class Cal_Tower;
   • This helps avoid name collisions.
   • This may be a good idea even when namespaces are available, you may want packages to have finer granularity than namespaces.
   
   
5. Avoid data with external linkage at file scope.
   • If the statement int i; occurs outside any blocks in a file, it is at file scope, and is therefore ``global data,'' and can conflict with names elsewhere in the program.
   • Global data tends to reduce modularity.
   • The reduced ``locality of reference'' from the use of global data reduces compiler optimization.
   • If global data is nonetheless needed, it should be implemented as private static data in a class with static accessor functions.
   
   
6. For similar reasons as for rule 5, also avoid (global) functions, enumerations, and typedefs at file scope. In general allow only classes, structs, unions, and definitions for overloaded operators at file scope.

7. If an entity is defined in a .cc file, it should be declared in the corresponding .hh file.
   • For example, if the following appears in a .cc file:
     

             void f(int x, int y){
               // function body here
             }

     then the following should appear in the corresponding .hh file:
     

     void f(int x, int y);

     (A point of style: C++ permits the names for arguments---x and y in this case---in the declaration to differ from the names of the corresponding arguments in the definition. It is better style, however, to use the same names in both cases, and to try to make those names meaningful.)

   • Following this rule makes it possible for compile dependencies to be obtained from the list of included header files.
   
   
8. Obtain the declaration for a function by including the .hh file of the component in which the function is defined.
   • If the argument list of a function changes, this needs to trigger a compilation of all components that use the function. The compilation dependencies are built from the #include statements.
   
   
9. When using a class, declare the class locally and only include the header file for that class if the compiler requires it.
   • The statement class Cal_Tower; is an example of a local class declaration.
   • Often, the compiler does not need to know the details of a particular class, and including the header file would introduce an unnecessary compile dependency between components.
   • Trying the compilation without the header file is the only reliable way to find out.
   • Examples of when the header file is needed:
     A class derives from another class, or contains an instance of another class as a data member.
   • Example of when a local class declaration is adequate:
     A member function returns an instance of that class.
   
   
10. Put inline functions into a separate .icc file which is then #included into the .hh file.

11. Large components can be broken up into many .cc files to improve compiler and linker efficiency.
    
    (On many systems, code residing in a library originating in one file is linked in on an "all-or-none" basis. So a single large file containing unrelated routines can cause code bloat.)

12. Put classes with their friend classes and functions in the same component.
    • Prevents other components from violating encapsulation by defining local versions of friends.
    • Friends are useful for iterators and global operator functions.
    • In general, minimize friend declarations, for maintenance reasons.
    
    
13. Avoid cyclic dependencies between components.
    Especially avoid cyclic dependencies between packages.
    • If two classes are interdependent, either break the dependency or put them in the same component.