User Tools

Site Tools


wiki:coding_conventions

Coding conventions

If anything isn't explained here, you should refer to document - Industrial Strength C++ (author page - http://www.henricson.se/mats/). Online version and pdf-version should be available here - http://www.sannabremo.se/nyquist/industrial/

Indentation & separation

All code should use 4 spaces for indentation. Lines of code should not be longer than 80 characters.

Position of the brackets is the following:

function ()
{    
    if (x == y)
    {
        // some code here
    }
 
    do
    {
        // code here
    }
    while ();
 
    if (very_long_expression &&
        that cannot fit on single line)
    {
 
        // code;
    }
 
    const char x[] =
    {
        "very long initializer that"
        "cannot fit into single line"
    };
}

To make the code more readable, all functions, class declarations and similar “units” of the code should be separated with:

//----------------------------------------------------------------------------- 

Separators are 79 chars long (77 bars and //), and placed before and after each function/class declaration, but without doubling, like this:

//--------[...]
function1()
{
}
//--------[...]
function2()
{
}
//--------[...]
class x1
{
}
//--------[...]

There should be a separator at end of each .cpp file, and .h file (with #endif and a blank line beneath)

When using comments to describe functions, put it under separator, like this:

//---------------------[...]
// Function: getColumnNames
// Params:   db             database object
//           tableName      name of the table
// Returns:  Array of strings containing column names
wxArrayString getColumnNames(IBPP::Database db, wxString tableName)
{
}
//---------------------[...]

Names

Variable names use camelCapitalization with a lowecase initial. Example: Database myDB = …;

Class names should use CamelCapitalization, with uppercase initial.

There's no special difference in naming between abstract and concrete classes.

Class data members names use camelCapitalization with a lowercase initial (like variables) and a M suffix, like someDataM. Class data members should be private unless there is a very good reason to do otherwise.

Member functions use camelCapitalization and lowercase initial too; example: getDatabaseInfo();

File organization

Each class declaration resides in a .h file with the same name of the class. Each class definition resides in a .cpp file with the same name.

Satellite classes may be declared and defined in the same files as the main classes they work with; groups of classes that closely work together may be defined in the same files. For the rest, apply the rule of thumb of one class per file.

Header files

This section contains information about how to write header files and #include directives.

Ordering

Ordering of included header files is strict:

  1. wxWidgets includes
  2. std includes
  3. IBPP includes
  4. other non-FlameRobin includes
  5. FlameRobin includes

Single header files may follow after another, groups of headers should be separated by an empty line. Library (std…) includes shold use the <> syntax, while FlameRobin includes should use the “” syntax. Alphabetical ordering within the groups strongly suggested. Example:

#include <wx/cmdline.h>
#include <wx/stdpaths.h>
#include <wx/utils.h>
 
#include <vector>
#include <string>
 
#include <ibpp.h>
 
#include "config.h"
#include "gui/MainFrame.h"
#include "main.h"
#include "ugly.h"

Completeness

Every header should include all necessary headers, so that it can be included in cpp files without additional requirements.

Minimal inclusion of other headers

A header shall only be included in another header when a forward declaration of the needed class(es) will not suffice.

Spacing

Binary operators have one space before and one after. Example: if ((x + y) > a)

Unary operators have no space between them and their operands. Example: c++ This includes the address operator (&).

The pointer (*) and reference (&) modifiers have no space between them and the type, and a space between them and the variable. Examples:

Database& d = ...
Table* t = ...
MetadataItem* findByName(string name);

These characters have always one space after them and never a space before them: “;”, “:”, “,”.

Round brackets have no spaces before or after, except for open round brackets after keywords. Examples:

if (...)
while (...)
for (...)
string foo(int a);
s = foo(12);

The general rule for round brackets is that you don't put spaces beside them in expressions, function definitions and function calls, and you do in other statements.

Curly brackets are always alone on the line (except for an occasional ; after a close curly bracket).

Miscellaneous rules

This section lists rules and convention not easily categorized elsewhere.

Class declarations

In a class declaration, the order of the sections should be consistent:

  1. private
  2. protected
  3. public

Constructors and destructors should be declared first in the section they belong. DECLARE_EVENT_TABLE(), if applicable, should be at the end of the class declaration.

Grouping of function definitions in cpp files

The larger the file the more important it is to keep function definition ordered. All member functions of a class should go together. If the file defines more than one class, then the definitions should appear in the same order as in the header file. If the file defines global functions, these definition should appear before member functions of any class. Member functions of a class should be defined in this order:

  1. constructors and destructors
  2. implementation member functions
  3. (were applicable) the message map and the message handlers

For very large files a separation of public and private + protected member functions is beneficial.

Usage of the Standard Template Library

FlameRobin makes use of the “std” namespace liberally. A remark about std::string: wherever possible, the FlameRobin code uses wxString instead.

Inline functions

Inline functions should be defined in an implementation (.cpp). Function definitions in declaration (.h) files should be avoided whenever possible.

wiki/coding_conventions.txt · Last modified: 2010/01/05 13:43 by mariuz