## Documentation It is important that your code is clear and easy to read, as a minumum you should write [doxygen](http://www.stack.nl/~dimitri/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. [an error occurred while processing this directive]