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