C ++ Coding Conventions



These conventions are intended to ensure that the contributions to the library from different people are reasonably consistant in style and of high standard. Most of these conventions are commonly applied anyway. Others, such as "all data members will be private", may surprise some people. This convention is there to encourage engineers to stick to the open-closed principle of class design (see our design philosophy for a explanation of this principle).

We don't expect people to stick rigidly these conventions, common sense needs to be applied to most of them. All contributions will be gratefully received, whatever the style employed. However, the closer contributors apply these standards the easier our life will be.

mandatory

desirable

  1. Standards
    1. All non-system coding shall be in accordance with the ISO C++ standard
    2. System calls will be avoided but when necessary will conform to the POSIX standards
  2. Layout
    1. Code shall be indented to show logical structure and flow of control
    2. Corresponding pairs of brackets occurring on different lines shall be positioned in the same column
  3. Documentation
    1. Documentation will be provided for each class in HTML format
  4. Comments
    1. All code will be well commented
    2. The // style of comment should be used for all comments
    3. Comments will be place at the start and finish of all classes
  5. Header files
    1. Header files will have suffix .h
    2. Header files may contain:
      1. Type definitions
      2. Templates
      3. Function declarations
      4. Inline function definitions
      5. Data declarations
      6. Constant definitions
      7. Enumerations
      8. Name declarations
      9. Include directives
      10. Comments
    3. They may not contain:
      1. Ordinary function definitions
      2. Data definitions
      3. Constant aggregate definitions
    4. A header file x.h will define and test a preprocessor variable X_H to prevent multiple inclusion in the same translation unit
    5. Every file will contain #include statements for all the header files on which it depends
  6. Implementation files
    1. Implementation files will have the suffix .cpp
    2. Implementation files may contain:
      1. Method definitions
      2. Definitions of static class members
    3. Implementation files may not contain:
      1. Variables in global scope
  7. Names
    1. Names of templates, classes and functions to begin with an uppercase letter, unless they mimic or extend the standard library containers or generic functions, in which case they will follow the stl lowercase style. Other names to begin with a lower case letter
    2. Names will only contain abbreviations if very obvious
    3. Words within a name will start with an upper case letter
    4. Names will be less than 20 characters long
  8. Preprocessor statements
    1. No constants or macros will be defined in preprocessor statements where alternative language facilities are available
  9. Classes
    1. All classes will contain at least one constructor in addition to a copy constructor, a destructor and an assignment operator
    2. Any class which contains a virtual function will have a virtual destructor
    3. Class initialisation lists will be ordered to correspond with the order of declaration
    4. Data members all will be private
    5. Classes will be associated with an output function where appropriate
  10. Methods and Functions
    1. No code will rely on the order of argument evaluation
    2. Methods and functions will not have variable argument lists
    3. Parameters will be declared with const when they, or what they refer to, is not altered by the function or method
    4. Methods will be declared const when they do not alter class members
  11. Booleans and Strings
    1. Built-in type bool will be used for Boolean types
    2. The string class from the Standard C++ library will be used in preference to char * strings
  12. Casting
    1. Run time type identification (RTTI) will be used rather than older style casts (when compilers allow)
  13. Libraries
    1. The Standard C++ Library will be used whenever it offers an acceptable facility
    2. All input/output will use the iostream facilities of the standard library
    3. No proprietary libraries will be used


Go Back to the Software Engineering Home Page Any questions and bug reports to Mark Williams. This page was last updated on the 25th of May 1999.