Help:Manual of style

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/func 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 nv 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. dcl family templates are used to handle the formatting.

Description

The description usually contains a bit of text that explains the behavior of class/function/object/etc and additional information that is categorized into separate sections (see below).

The first sentence of the description text must summarize the behavior of the feature. The length of it should not exceed ~200 characters (that's about two lines of text).

Classes

The description of a class generally follows the following pattern (list of sections in order):

• Synopsis
• Description text
• Template parameters (if the class is a template)
• Member types (Public/Private/Protected/Exposition-only)
• Member functions (Public/Private/Protected/Exposition-only)
• Member objects (Public/Private/Protected/Exposition-only)
• Non-member functions
• Helper types
• Helper classes
• Notes (may include FTM table)
• Example
• Defect reports (if any)
• References (links to the normative docs)
• See also
• External links (if any)

dsc 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. {{dsc 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 {{dsc inc}} to include them.

For example:

In cpp/component/class

 
  {{dsc begin}}
  {{dsc h1 | Member functions}}
  {{dsc inc | cpp/component/class/dsc fun_function}}
  {{dsc end}}
  

In cpp/component/class/another_function

 
  ...
  ...
  ===See also===
  {{dsc begin}}
  {{dsc inc | cpp/component/class/dsc fun_function}}
  {{dsc end}}
  

In Template:cpp/component/class/dsc fun_function

 
  {{dsc 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.

Functions

The description of a function generally follows the following pattern (list of sections in order):

• Synopsis
• Description text
• Template parameters (if the function is a template)
• Parameters
• Return value
• Exceptions
• Complexity
• Notes (may include FTM table)
• Possible implementation
• Example
• Defect reports (if any)
• References (links to the normative docs)
• See also
• External links (if any)

All function parameter names are written in monospace font.

par 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.

Niebloids

The description of a niebloid generally follows the same pattern as that of a function, except that the introduction should include {{cpp/ranges/niebloid}} (?)

Concepts

The description of a concept generally contains only description.

See also list

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

Code formatting

Capitalization

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 examples 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)
    {
        std::cout << argv[0] << '\n';
        std::cout << argv[1] << '\n';
    }
    else
        std::cout << argv[0] << '\n';
}

Not all of these rules apply for the detailed feature declarations (those going into {{dcl ***}} 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 <     class TemplateParam,     class TemplateParam2 > class TemplateClass;
template< class TemplateParam, class TemplateParam2 > int function_template( MyTemplate<T,Param> my_template_param,                        int* other_param );