Skip to content

Coding conventions

Jump to bottom
Kai Pastor edited this page Mar 17, 2018 · 15 revisions

This is a list of coding conventions used by the OpenOrienteering Mapper project, roughly ordered by importance. It is not demanded to obey these rules slavishly, but most of all when changing existing code they should help to retain a clear formatting.

Key guidelines

File names

Use lowercase with words separated by underscores, for example some_project_file.cpp. Use .h for headers, .cpp for implemenation.

Includes

Includes are separated into up to four blocks:

  1. For .cpp files, the include for the respective header. Just the filename, no path.
  2. Includes for standard library headers. Prefer C++ includes over C ones.
  3. Includes of third party headers (Qt etc.).
  4. Includes of other headers in this project. Specifiy the path relative to the src directory, even if the files is in the same directory.

Inside the blocks, use alphabetic order. (Qt Creator can sort selected lines, shortcut Alt+Shift+S.) However, it is preferred to put Qt headers for global definitions (<Qt>, <QtGlobal> etc.) before Qt headers for particular types (<QLabel> etc.).

Include what you use: For any feature you are using, either forward declare the feature if this is possible and sufficient, or include the relevant header. Do not rely on transitive inclusion.

Example for a file called "this_file.cpp":

#include "this_file.h"

#include <memory>
#include <cassert>

#include <QtGui>
#include <liblas/liblas.hpp>

#include "core/map.h"
#include "gui/map/map_widget.h"

Indentation

Use tabs with a width of 4.

Naming

  • Variable names are lowercase and words are separated with underscores: num_objects
  • Class names are in camel case and start with an uppercase letter: PointSymbol
  • Method names are in camel case and start with a lowercase letter: PointSymbol::setName(const QString& name)

Example:

class ExampleClass
{
public:
    void getSomethingDone();
    float makeCrazier();

private:
    int some_integer;
    float degree_of_craziness;
}

Braces

Braces are normally opened on the next line, except in a few cases. Examples:

// Normal case
if (random)
{
    cutGreenWire();
    explode();
}
else
{
    cutRedWire();
    implode();
}

// Special case
inline void veryShortMethod() { veryShortContent(); }

Exceptions

Avoid exceptions. However, there may be good reasons to use exceptions for unexpected error conditions.

Qt5-style connect()

Use the pointer-to-member-function style for connects where possible.

Support constness

Provide and use const implementations of methods where possible. Similar for const references.

Modern C++

Pointers

Unless interfacing with Qt (QObject ownership), consider using std::unique_ptr/std::make_unique.

Almost always auto (AAA)

Use of auto for local variables is encouraged.

Lambdas

Use of lambdas for local helpers is encouraged.

constexpr, noexcept, move-semantics

The proper implementage and usage of constexpr, noexcept and move semantics is encouraged.

Auxiliary guidelines

Common C++ guidelines

The following guidelines provide excellent advice, although not points apply to Mapper:

Containers

  • Keep in mind that at least the Android port may run under low memory conditions.
  • Prefer (carefully chosen) standard library containers over Qt containes.
    • Prefer std::vector over QHash and friends for small structures (hint: strong locality, low memory fragmentation).
    • However, when interfacing with Qt, there is no need to enforce additional conversions.
  • Beware the expensive detaching of implicitly shared Qt containers on some operations, e.g. in range-for loop.

Think internationalization

Please make sure to use tr() on all strings which need to be translated. See Translation for more information.

Clone this wiki locally