Code_style

Keeping a consistent code style helps code readability, and reduces confusion.

• Names
  • Variable and Function Names
  • Class names
  • Macros and enums
  • File names
• Spacing
• Indents
• Documentation
• File header

Names

I generally avoid names with abbreviations, especially in class members and functions.

Variable and Function Names

Variables and functions should be named with lower case letters. When a name consists of multiple words, separate them with underscores. Functions should be distinguishable from variables because a function has a verb.

Class names

Class names are written in CamelCase, with the first letter capitalised.

Macros and enums

Macros and enums use block capitals with underscores between the words.

You should generally avoid using macros. However to protect against multiple inclusions of the same header file, write this near the top of a header file (replacing FILE_NAME with the name of the file formated with the rule above):

#ifndef FILE_NAME_H_
#define FILE_NAME_H_

and this at the end

#endif // FILE_NAME_H_

When it is likely that the filename may be used multiple times, put part of the path in the macro name.

File names

File names are normally the same as the classes contained within them with .h or .cpp added on.

Spacing

Brackets don't need spaces around them. Other operators should have a space either side, except there should be no space before the , operator. Try to keep lines of code shorter than 80 characters.

For readability, sometimes it helps to add extra spaces to make things line up with surrounding lines.

Indents

Use four spaces. Braces go on their own line, indented to the outer level. After the 'case x:' lines in a switch block I indent another time. Tabs are evil, don't use them :-)

It acceptable to combine the braces around else into one line

Example:

void Object::Example(int argument_one, int y)
{
    if (condition)
    {
        do_something(argument_one, argument_two);
    } else {
        x[0] = y * 2;
    }
}

or

void Object::Example(int argument_one, int y)
{
    if (condition)
    {
        do_something(argument_one, argument_two);
    }
    else
    {
        x[0] = y * 2;
    }
}

Documentation

I use Doxygen to document my code. Doxygen picks up line comments begining with an extra /, (/// comment) and block comments begining with an extra * (/** comment */). It can generate documentation in a variety of outputs. Read http://www.stack.nl/~dimitri/doxygen/docblocks.html for an overview of how to document the code.

To generate the documentation, run doxygen Doxyfile in the 'trunk' directory. HTML Documentation is generated and saved in documentation/html/. At some point I would like to have this automatically done and uploaded to the project's web space on Sourceforge every day, but I don't know how.

File header

Begin each file with this template. This should avoid packagers complaining there is code with unspecified distribution terms.

/** @file path_if_necessary/FileName.h
 *  @brief One line description of the file.
 *  @author author's name
 */
/* Copyright © year author's name.
    This program is free software: you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation, either version 3 of the License, or
    (at your option) any later version.
*/

Change the template to use your name, the year, the file name (and part of the path if there are likely to be multiple files with this name), and write a short brief for the file.

If you modify a file, add another @author line and author into the copyright line if necessary, and list the year if it is not already included.

[Category:Development]