Help:Manual of style

Revision as of 10:47, 16 May 2013 by P12 (Talk | contribs)

This page contains a design guideline that helps to follow consistent style and formatting in this wiki. Note, that the guideline list is neither final nor complete, i.e. new guidelines can be added and the current changed if there's benefit to do that.


Page structure

Most of the pages in this wiki have the following pattern:

Title override

Title override is almost mandatory, MediaWiki displays the path of the page otherwise.

If the feature is not a member of any classes, the title is overridden directly using {{ctitle}} or {{cpp/title}}. Otherwise, a helper template that abstracts the container class name is created. For example consider std::class::func():

cpp/blah/class/erase contains {{cpp/blah/class/title|func}}

whereas Template:cpp/blah/class/title contains {{cpp/title|n=class|{{{1}}}}}. This helper template is used for all members of that class.

Navigation bar

Navigation bars are used to improve the navigation by providing links to relevant pages. A navigation bar is usually implemented using the {{navbar}} template. The resulting definition is usually put to Template:path/to/page/navbar.

The {{navbar}} template defines a heading which is always visible and content that is shown on hover. The definitions of both are usually put into separate templates at Template:path/to/page/navbar heading and Template:path/to/page/navbar content respectively.

The content is usually a list of related functions and classes. The list is usually implemented using sb list family of templates.

The definition of the navigation bar includes the heading and content templates of each of its parent pages.

{{mark c++11}} should be used in navbars instead of {{mark since c++11}} to conserve space.

Declaration of the class or function

The declaration is put as is defined in the header. The template and parameter names are renamed according to the common names in this wiki if possible. {{ddcl list ...}} templates are used to handle the formatting.



The description of a class generally follows the following pattern:

  • Description
  • Template parameters if the class is a template
  • Member types
  • Member functions
  • Member objects
  • Protected member types
  • Protected functions
  • Protected member objects
  • Non-member functions
  • Helper types
  • Helper classes
  • Notes
  • Example

{{dcl list ...}} template family is used to handle the formatting of lists of member types, functions or objects, as well as lists of related non-member functions or classes.

Usually the same member description bits (e.g. {{dcl list mem fun| cpp/component/class/fun_function| description of the function}}) would be included into See also section of other pages. To reduce the duplication, it's worth to put those bits into separate templates and then use {{dcl list template}} to include them.

For example:

In cpp/component/class

  {{dcl list begin}}
  {{dcl list h1 | Member functions}}
  {{dcl list template | cpp/component/class/dcl list fun_function}}
  {{dcl list end}}

In cpp/component/class/another_function

  {{see also}}
  {{dcl list begin}}
  {{dcl list template | cpp/component/class/dcl list fun_function}}
  {{dcl list end}}

In Template:cpp/component/class/dcl list fun_function

  {{dcl list mem fun | cpp/component/class/fun_function | description of the function}}

If the same description bits are used across several classes, as is, e.g. in the Containers library, one template can remove duplications in as many as 20 places.


The description of a function generally follows the following pattern:

  • Description
  • Parameters
  • Return value
  • Exceptions
  • Complexity
  • Notes
  • Possible implementation
  • Example

All parameter names are written in monospace font.

{{param list ...}} template family is used to handle the formatting of parameter descriptions.

(none) is used to indicate absence of parameters, return value or thrown exceptions.

{{eq fun}} can be used to format equivalent code

{{example}} can be used to format examples

Object, constant, types

The description of an object, constant or type generally contains only description.

See also list

Lists the relevant functions, classes, etc. {{dcl list ...}} template family is used to handle the formatting.

Code formatting


Names are capitalized in the same way as in most of the C++ standard. The documentation of the standard components should follow the following style:

  • function parameters use small_caps style
  • template parameters use CamelCase style

In examles and other documentation, the following additional guidelines apply:

  • custom class names use CamelCase style
  • variable names use small_caps style
  • macro and constant names use ALL_CAPS style

Spacing and indentation

  • K&R indentation style is used (see K&R TBS).
  • Standard constructs, i.e. for, while, if, etc have a space between identifier and opening parentheses, e.g.
    for (...).
  • There is no space between function name and the parentheses, as well as between the parentheses and the content between them, e.g. fun(...).
  • There is no space between template name and < symbol, as well as between < and > symbols and the template parameters, e.g. tmp<...>.
  • Multiple function or template parameters are separated by space after the comma.
  • There is no space between reference and pointer (& and *) modifiers and the type name (e.g. int& b).
  • If the parameters of a function span several lines, the indentation of all parameters matches the opening parenthesis. The same goes for template parameters.

For example:

#include <vector>
std::vector<int, MyAllocator> v;
int complex_function(int long_param_name,
                     int& another_param_name);
int main(int argc, char** argv)
    if (argc == 2) {

Not all of these rules apply for the detailed feature declarations (those going into {{ddcl list ***}} template), since extra readability is needed. The exceptions include:

  • There is space between the < and > symbols and template parameters for function templates.
  • Class templates have their parameters laid out through several lines.
  • For function parameters, that are templates, there are no spaces between the < and > symbols and the template parameters. Also, there is no space after the comma separating the template parameters.

For example:

Template:ddcl list begin <tr class="t-dcl ">

<td class="t-dcl-nopad">
template <

    class TemplateParam,
    class TemplateParam2

> class TemplateClass;

<td class="t-dcl-nopad"> </td> <td class="t-dcl-nopad"> </td> </tr> <tr class="t-dcl ">

<td class="t-dcl-nopad">
template< class TemplateParam, class TemplateParam2 >

int function_template( MyTemplate<T,Param> my_template_param,

                       int* other_param );

<td class="t-dcl-nopad"> </td> <td class="t-dcl-nopad"> </td> </tr> Template:ddcl list end