You may contribute to this page until it becomes a specification.
Per-project needed files
Each project should have in the root of its directory structure (e.g. the top level directory) the following files :
This file lists all mandatory and optional dependencies to build the project. Here is an example taken from the old game client source tree :
* Boost.Test 1.34
+ Needed for unit tests
First line contains the software or library name and version. The second line is very useful, indicating if the dependency is needed or optional. The homepage and download links follow.
This file must follow the GNU
format. Here is a sample :
2011-01-03 Jerome Pasquier <email@example.com>
* src/Makefile.am (SUBDIRS): testHelpers do not depends on
* src/maincore/inputmanager.cpp (initialise): Try to get
D3DX9 window handle.
* acinclude.m4 (RB_CHECK_OGREMAIN): Added include flags for
Additionally, a changelog.dev
file (or a directory containing several files) may be created to contain very old revisions summaries.
A non-detailed list of things to do including previous revision, current revision's item tracking and statistics. If you don't know what is a revision
or a revision's item
, please see our VersioningPolicy
A very detailed file in org-mode
, used both as a GTD
management system and a time tracker.
All the following statistics go in the top directory's
file and must be added to each closed revision
SLOC : the currently number of Source lines of code, obtained using David A. Wheeler's sloccount.
FT : The
ROADMAP file time using the
org-clock-display of org-mode.
UT : The number of implemented unit tests. You can usually get it through the
make check command.
Adding the version
, the revision
and the start and end dates (in the DD mmm YYYY format), you get a line like this
* v0.0.5-212 (19 mar 2011 - 27 may 2011) SLOC 43,269 UT 270 FT 100:03
- Started Font's unittests implementation
- Started Glyph's unittests implementation
- Client now works in debug mode
... <more items may follow>
All sources always go in
. Unit test implementation goes in the same directory of the source it tends to test, postfixed with the
word. Example :
The maximum length of a line for code or comments is 78 characters. You must split long lines. Tabulation char (i.e. indentation) is two white space characters and GNU headers are needed on each source file (header or implementation).
It is a good idea to keep a clean header file because we often take a look at it instead of generating whole doxygen
documentation. The following rules help keeping clean header files.
Always document files with the
command (see online documentation
, to get generated documentation for
/** \file GuiManager.hpp
* Declares a singleton used to manage GUI objects.
This comment block must be placed after
the GNU headers.
Classes documentation (includes typedefs
and others) is in the header file, at the top of the corresponding keyword.
Documentation for function goes in the implementation file (e.g. the .cpp
file). It should follow the following structure, removing empty sections and adding empty line between section headers :
| Section name
| Brief description
|| A one line description of what the function actually does.
| Detailed one
|| A more detailed description, possibly containing headers and multiple paragraphs.
|| One or more conditions needed before the call of this function.
|| One or conditions always true after the call of this function.
|| All parameters of the function and their meaning.
| Return value
|| The function return value description.
Always document all parameters and non-void return values to avoid undocumented members
Use explicit \ref
commands to get warnings on misspelled or undocumented types.
For class members, try to put documentation after members (with
or other accepted syntax). If the member needs more then a brief description, please add full documentation in a in a
block before the member it tends to document.
int bar; //!< The brief description
C++ programming language
#include statement documentation
You must document the headers you include. When you know why a file is included, you may start to understand the header you are reading.
|| this class inherits from the class in the include file.
|| this class contains, as a member attribute, the class in the include file. This class owns the memory and is responsible for deleting it.
|| this class uses something from the include file.
|| this class keeps a pointer or reference to the class in the include file, but this class does not own the memory.
#include <istream> // standard IO interface
#include <string> // HASA string interface
#include <memory> // USES auto_ptr
Briefly, need rewriting :
- We will use only one namespace named
Rpg to replace the actual weird names.
- Filenames are in UpperCamelCase but sometimes, to denote a hierarchy, file names can be prefixed with short lowercase prefix. A good example can be found in the game client game states files, where we use a gs prefix which stand for
- Header have
.hpp extension while implementation have
- Classes and type names are UpperCamelCase, functions names are lowerCamelCase.
- Always use initializer list
- Remember following the Rule of three.
- Consider using pre-increment instead of post-increment where possible.
- You might take a look at useful tools such as cppcheck and valgrind.
- Always set a space character before the opening parenthesis of the parameters when you call a function.
- Add a newline after the return value of a function signature in implementation file.
C programming language
We do not use many Ansi C
code in this project, but I personally do, so I add this section as reference. The main difference with the C++ standards
are the way I name functions
: in Ansi C, I always lower_case
) as word separator. The filenames use also .h
extension for headers and .c
extension for implementation files.
The following links were sources of inspirations :
- 05 Aug 2011