Introduction

This document defines and formalizes the presentation and redaction of all source files. A strict adherence to these conventions is required to ensure a readable and understandable code.

File Naming

There are very few restrictions on file names and locations. The following rules are expected:

File Locations

A quick check of the source directory will show how files are organized within the source tree. The sources are organized in two levels.

The first level specifies which part of the platform the source belongs to:

The second level specifies the types of data:

or

NOTE: The directory include only contains public headers, if you have private headers put them in src.

The third level specifies which logical part the file belongs to:

This applies to basic source as well as include files, who are in a separate include tree and never along their source code files. Thus, an include declaration would be:

#include "nel/misc/steam.h" 

 

File Header

All code files must begin with a specific header. The model of that header is defined in headers.txt in the documentation directory. It is recommended that people include that file immediately when starting a new file.

Basic Types

Integral Types

Examples: uint8 (unsigned 8 bit integer), sint64 (signed 64 bit integer), sint (signed integer of at least 32 bits)

Classic Types

As a general rule, the classic and sloppy use of short / int / long is proscribed, as is using a char to represent a 8-bit number, unless this is required to call an external API. a char should use only when you want to represent a ASCII character.

Naming Convention

All elements will be in their own namespace, which is short, in all uppercase, and consist of a two letter code (NL for NeL), followed by the directory name. Thus an element of the NeL 3D library will be declared in the NL3D namespace.

The following conventions are applied to names within these namespaces:

Note that there is no difference between variables and constants.

Coding Style

Indentation

A strong suggestion is to set your tabulation marks to 4 characters, rather than the usual 8. Indentation is always done using tabulations, never with spaces. Make sure your text editor does not replace tabulations with spaces.

If possible, function, members and variable lists should align the first character of all their names.

Braces

Source code is written using a flat style. In this style, the opening and closing curly braces are placed on separate lines (never with code), and at the same indentation as the preceding defining element, while the content of the block enclosed between the braces is indented once from the source. Your code source should look like this:

class CDummy
{
    void dummy (uint32 b)
    {
        if (b == 0xDEADBEEF)
        {
            // ...
        }
    }
}; 

 

Comments

Comments may use either the C++ style comments //, or the more classic C commenting method. If possible the source must be heavily commented and as many comments as possible must conform to the Doxygen commenting methods so that they can be extracted and reused as software documentation.

Comment "separators" will be made with a line of repeated star '*' characters. You should not use more than 50 stars to separate.

The practice of comment blocks, comments where each line begins and end with a star character, to create a "text block" is proscribed.
Final Coding Recommendations

Even if most of these are obvious recommendations, it is useful to restate these basic principles: