General Code Layout

Documentation

It is important that your code is clear and easy to read, as a minumum you should write doxygen for every class, member, type and method. The practice of writing self documenting code which explains why something is being done and not what is being done. More examples of this will be given in lectures.

Header files

Each header file follows the format :

/// \brief encapsulates a 4d Homogenous Point / Vector object
/// \author Jonathan Macey
/// \version 3.0
/// \date 28/9/09 Updated to NCCA Coding standard
/// Revision History :
/// Initial Version 24/11/04
/// \todo lots of tidying up and code optimizations


#ifndef VECTOR_H_
#define VECTOR_H_

File Includes

Header Contents

#endif    // _FILENAME_H_

Include Guards

Each header file must have an include guard placed immediately after its module header. These guard against multiple inclusion of the file, and follow the format: FILENAME_H_ For example for a source file called Vector.h we use VECTOR_H_ as shown

#ifndef VECTOR_H_
#define VECTOR_H_

File Includes

Header Contents


#endif // VECTOR_H_

Code Files

Each code file follows the format :

///
///  @file Name.cpp
///  @brief A short description of the module


#include <iostream>
#include "Name.h"

//Additional File Includes
#include "Vector.h"


// Module Contents

Including header files

<> is only to be used for standard C librarys. Everything else will use "" (this speeds up the build times by limiting the search paths to those you have manually specified).

The include should be located immediately after the header include guard or code module setup blocks. Wherever possible they should be listed in the following order :

System includes

Engine includes

Library  includes

Project includes

The files within each section should be listed in alphabetical order, except for system includes. A header file should ensure that all external definitions are either #included or forward-declared, and should not rely on the outer code module to include additional headers in any particular order.

Care should be taken to minimise the external dependencies for a header file by forward-declaring such classes, rather than #including them, wherever possible. This minimises the amount of code that needs to be rebuilt following changes to a header file.