Skip to content

Specification Style Guidelines

Jump to bottom
Thomas Köppe edited this page Nov 27, 2016 · 106 revisions

Standards Wording Idioms

This is a list of some common idioms in the standard that should be used to specify certain cases, and corresponding anti-idioms that should not be used.

When you are writing proposals for changes to the C++ standard, please try to follow these idioms. If you notice an anti-idiom in the current C++ standards draft, please [submit an editorial issue](How to submit an editorial issue).

Case Idiom(s) Anti-idiom(s) Example
Normative requirement (implementation)
Use this idiom when specifying something we require a conforming implementation to do.
  • The behavior of the program is […]
  • The implementation shall […] (only use this form when it is clear we are talking about the implementation)
  • […] must […]
  • an expression shall not have reference type

 "A conforming implementation executing a well-formed program shall produce the same observable behavior as one of the possible executions of the corresponding instance of the abstract machine"
Normative requirement (program)
Use this idiom when specifying something we require a well-formed program to do, and equivalently, for something whose converse we require a conforming implementation to diagnose.
  • A prvalue shall have a complete type […]
  • The -> operator shall not be […]
  • […] must […]
  • The program is ill-formed if […] (OK, but not preferred)

"A d-char-sequence shall consist of at most 16 characters"
Normative encouragement
Use this idiom when specifying something we would prefer, but do not require, implementations to do.
  • Implementations should […]
  • Implementations are encouraged, but not required, to […]
 "Implementations should ensure that all unblocked threads eventually make progress"
Complicated conditional cases
Use this idiom when you are enumerating a set of possibilities, and stating requirements under those possibilities.
  • If […], then […].
    If […], then […].
    …
    Otherwise […]
  • […], except when […], then […], or when […], then […]
 "If E1 is an lvalue, then E1.E2 is an lvalue; if E1 is an xvalue, then E1.E2 is an xvalue; otherwise, it is a prvalue."

Missing idioms

  • Variations on "ill-formed" (particularly, "no diagnostic is required" forms)

Library conventions

You can find a description of the conventions followed by the library clauses in the standard in the standard itself, in the section labeled Method of description (informative) [description] (section 17.5 in C++11).

Library-wide requirements are specified in the standard under Library-wide requirements [requirements] (section 17.6 in C++11). This section describes the type requirements (e.g. EqualityComparable and DefaultConstructible) as well as broad rules for library implementation and usage.

Writing "Let" in a function description

When describing the semantics of a library function, it's sometimes useful to introduce a new name for something, typically to shorten it. In that case, write a paragraph ahead of the Effects, Returns, and similar paragraphs to do so.

For example:

  1. Let T be decltype(foo).
  2. Returns: T{0}
  3. Requires: T shall be CopyConstructible.

Do not put a "Let" statement in the Remarks paragraph of a function description.

Writing Effects: in a function description

Effects: elements are used in the library to describe functions. They can be described in words, or in code preceded by an introductory phrase of some kind. The introductory phase "Equivalent to" is normative and has special meaning, as is described in [structure.specifications]/4. When code is used to describe an effects element, a colon (:) should follow the introductory phrase if the code is a statement or a code block, where as expressions should end with a period (.).

For example:

  1. Effects: The function works in this way.

  2. Effects: Equivalent to expression.

  3. Effects: Equivalent to:

     statement1;
 statement2;

Note that return 42 is not an expression (it's not an anything -- the return grammar production has a trailing ;), so this is wrong:

Effects: Equivalent to return 42.

and these are acceptable:

Effects: Equivalent to: return 42;

Effects: Equivalent to:

    return 42;

Writing Returns: in a function description

Returns: elements are similar to Effects: elements. They should always end in a full stop. They may be just a single expression, or phrase or sentence. If the text starts with normal text, it should be capitalized. Very long expressions may use a codeblock.

For example:

  1. Returns: !(a == b).

  2. Returns: true if foo; false otherwise.

  3. Returns: A copy of the object described in this sentence.

  4. Returns:

     a_very_long_expression()

Specifying implicitly generated special member functions

When you are specifying a class containing implicitly generated member functions, do not provide a detailed specification of these, as their behavior is implied by the language rules. Instead, list the member functions using the = default mechanism in the class synopsis only. For example:

class my_class {
  // ...
public:
  my_class() noexcept = default;
  my_class(const my_class&) = default;
  my_class& operator=(const my_class&) = default;
  my_class(my_class&&) noexcept = default;
  my_class& operator=(my_class&&) noexcept = default;
  ~my_class() noexcept = default;
  // ...
};

Formatting declarations and definitions

  • Template parameter names are camel-case.
  • Template type parameters use class not typename.
  • const goes to the left of the type it modifies.

Source code formatting

A typical paragraph of LaTeX should use the following conventions:

\pnum                                                    %% start with \pnum
\indextext{...}%                                         %% relevant paragraph-wide entries; no whitespace!
Lorem ipsum first sentence here,
defining a \defn{thing}\indextext{alternate entry}.
When needed,\footnote{mind the spacing} add a footnote.
\begin{itemize}                                          %% No blank line before!
\item Short item 1
\item Short item 2
\item Short item 3
\end{itemize}
\begin{note}                                             %% begin and end on their own lines
This is not normative.
\begin{example}
\begin{codeblock}
/* ... */
\end{codeblock}
\end{example}
You can nest examples in notes, or keep them as
consecutive siblings.
\end{note}
This is a very long paragraph, which is not great,
but we want to show off another list:
\begin{itemize}
\item
  For longer list items, indent each item by two.
  No additional blank lines are needed.
\item
  With this style, nested lists are easy as pie.
  \begin{itemize}
  \item Same rules as for all lists,
  \item recursively.
  \end{itemize}
\item
  We have too many lists
  in the Standard.
\end{itemize}
Finally this paragraph is coming to an end.

ISO Directives

Rules for the overall structure and form of ISO standards is provided by the ISO Directives, Part 2. This covers rules common to all ISO documents, such as the meaning of should and shall, and the referencing of other standards documents. However, the C++ standard provides requirements at two levels simultaneously (for a conforming implementation and for a well-formed program), and these terms are usually repurposed as describing the language rather than the implementation.

Clone this wiki locally