You are here: RainbruRPG>Concept Web>CodingStandards (10 Mar 2013, RainbruUser)

Draft

# Coding standards

## Language-independent standards

### Per-project needed files

Each project should have in the root of its directory structure (e.g. the top level directory) the following files :

#### DEPENDENCIES

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
+ homepage:
http://boost.org
http::/sourceforge.net/projects/boost/files/

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.

#### ChangeLog

This file must follow the GNU format. Here is a sample :
2011-01-03 Jerome Pasquier  <rainbru@free.fr>

* src/Makefile.am (SUBDIRS): testHelpers do not depends on
RB_OPTION_TESTS_FLAGS anymore.

* src/maincore/inputmanager.cpp (initialise): Try to get
D3DX9 window handle.

* acinclude.m4 (RB_CHECK_OGREMAIN): Added include flags for
d3dx9.h.


Additionally, a changelog.dev file (or a directory containing several files) may be created to contain very old revisions summaries.

#### TODO

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.

### Per-project statistics

All the following statistics go in the top directory's TODO 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>


### Sub-directory structure

All sources always go in src/. Unit test implementation goes in the same directory of the source it tends to test, postfixed with the _Test word. Example :
Logger.cpp
Logger_Test.cpp


### Code presentation

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).

## Documentation

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.

### Files

Always document files with the \file doxygen command (see online documentation, to get generated documentation for #define macros :
/** \file GuiManager.hpp
* Declares a singleton used to manage GUI objects.
*
*/

This comment block must be placed after the GNU headers.

### Types

Classes documentation (includes typedefs, enumerations, unions and others) is in the header file, at the top of the corresponding keyword.

### Functions

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 :

Brief description A one line description of what the function actually does.
Detailed one A more detailed description, possibly containing headers and multiple paragraphs.
Precondition One or more conditions needed before the call of this function.
Postcondition One or conditions always true after the call of this function.
Parameters 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 warnings.

Use explicit \ref commands to get warnings on misspelled or undocumented types.

### Members

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.

class Foo
{
int bar; //!< The brief description
};


## Language-independent standards

### 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.

 ISA this class inherits from the class in the include file. HASA this class contains, as a member attribute, the class in the include file. This class owns the memory and is responsible for deleting it. USES this class uses something from the include file. HASA-USES 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 GameState :
GameState.hpp
gsLocalTest.hpp

• Header have .hpp extension while implementation have .cpp oe.
• 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, structures and types : in Ansi C, I always lower_case names, using _ (underscore) as word separator. The filenames use also .h extension for headers and .c extension for implementation files.

## References

The following links were sources of inspirations :

## Concept table

04 jun 2011 RainbruUser Draft A basic stub. Need refactoring and many more details.
19 Jul 2011 RainbruUser Draft Added C programming language section. Improved C++ one.
05 oct 2012 RainbruUser Draft Many details added, some section improved.

-- RainbruUser - 05 Aug 2011
Topic revision: r11 - 10 Mar 2013, RainbruUser

Viesearch - Life powered search
Copyright © by the contributing authors. All material on this collaboration platform is the property of the contributing authors.