-
Notifications
You must be signed in to change notification settings - Fork 774
Specification Style Guidelines
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. |
|
|
"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 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 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 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." |
- Variations on "ill-formed" (particularly, "no diagnostic is required" forms)
(Decided in #2150.)
-
Do not use trailing parentheses to mean simply "this name is a function". You may use trailing parentheses when referring to an overloaded function to specify which overload you mean, but if this comes up we should discuss a better way of naming it, such as "the blah(int) overload".
-
When we say "Calls blah", blah should be an expression that results in a function call. Eg, "calls operator new(size)" or "calls `current_exception() and stores the returned value".
-
As an alternative, you may use "Calls blah with foo", and in that case blah should be a function.
-
The form "Calls to the function blah do X, Y, Z" is also OK, and blah should denote a function not an expression. (Per the first bullet, there should be no parentheses unless the function is overloaded.)
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.
Descriptions for library entities should be grouped into reasonably-sized subclauses. Avoid multiple consecutive subclauses that each describe only one function. A rule of thumb is 1-3 subclause headings per library description page. (See below for synopses.)
Do not repeat parts of subclause headings in nested headings (decided in #1242). Good: "Class template tuple" / "Construction". Bad: "Class template vector" / "vector capacity".
Prefer prose text over C++ tokens in subclause headings. Good: "Concatenation". Bad: "operator+".
The following subclause headings and label parts are good:
- Constructors [*.ctor] (not: Construction) [decision required]
- Assignment [*.assign]
- Member functions [*.members]
- Observers [*.obs]
- Modifiers [*.mod]
- Equality operators [*.eq]
- Relational operators [*.rel] (note: neither == nor != is a relational operator)
- Comparison [*.cmp] (includes equality and relational operators)
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:
- Let T be decltype(foo).
- Returns: T{0}.
- Mandates: T shall be CopyConstructible.
Do not put a "Let" statement in the Remarks paragraph of 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, whereas expressions should end with a period (.). For "Equivalent to", a plain expression should appear only if it is of type void; for value-returning functions, use return expression; (see below).
For example:
-
Effects: The function works in this way.
-
Effects: Equivalent to expression.
-
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;where 42 is explained further in trailing text.
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 (without a full stop at the end).
For example:
-
Returns: !(a == b).
-
Returns: true if foo; false otherwise.
-
Returns: A copy of the object described in this sentence.
-
Returns:
a_very_long_expression()
Do not use the Requires: element; the Expects: and Throws: elements should be used instead.
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;
// ...
};
These rules apply within library clauses. Within core clauses, we intentionally use a variety of different styles to emphasize that the core language does not enforce any particular style.
- Use two-space indentation when breaking a declaration after a template-head or return type; (class) definitions do not indent after the template-head; indent to the active
<or(when breaking within a template or function parameter list. #1754 - Template parameter names are camel-case.
- Template type parameters use
classnottypename. -
constgoes to the left of the type it modifies. -
&,*,::*, and...have no space on their left-hand side, and have a space on their right-hand side unless another operator appears next. - Do not insert whitespace between
operatorand the following token except in a conversion-type-id. Examples:operator(),operator""if, butoperator (int(*)()). - Use
nullptr, not 0, for null pointer values.
Use semantic line breaks in LaTeX source code: http://sembr.org/ and http://rhodesmill.org/brandon/2012/one-sentence-per-line/
A typical paragraph of LaTeX should use the following conventions:
\pnum %% start with \pnum
\indextext{...}% %% relevant paragraph-wide entries,
\indextext{...}% %% one per line; 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 and end on their
\begin{note} %% own lines if possible
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.
Codeblocks follow some loose conventions. Indentation is by two spaces. Indentation is applied when a function declaration contains linebreaks after the template signature or the return type:
template <typename T> void foo(T);
template <typename T, typename Iter>
std::vector<T> a_longer_function_name(Iter first, Iter last, T& out);
template <typename T, typename Iter>
std::vector<std::iterator_traits<Iter>::allocator_type, const T*>
a_hypnotically_longer_function(Iter first, Iter last, const T& in, T& out) noexcept;
In example code, line comments (//) are indented according to certain rules:
- The comment column number must always be a multiple of 4.
- There must be at least one space between code and comment.
- If possible, there should be at least two spaces between code and comment.
- We have a strong preference for columns 20, 32 and 40 (then 48, 64). Text within a region (e.g. a spread or two) may try for a common column. If there is a column value that works well except in a handful of isolated cases, Rule 3 may be violated to accommodate this.
- In a header synopsis and in a class definition, have
namespace std {. - In a header synopsis, declarations of class and function templates should have a linebreak+indent after the
template <...>head. In a class template definition, there is no additional indent after thetemplate <...>head, and the linebreak after the template head is optional. - An
itemdeclneed not be a literal copy/paste of the synopsis entry; usually it can use fewer lines since it is wider. It is permissible to have function templates on a single line here, but it is also fine to retain the linebreak after the template head.
// synopsis
namespace std {
template <typename T>
struct foo;
template <typename T, typename Alloc = allocator<T>>
class bar;
}
// class definitions
namespace std {
template <typename T> struct foo {
void abc();
};
template <typename T, typename Alloc = allocator<T>>
class bar {
public:
// \ref{bar.construct} constructors
bar(int a, int b);
template <typename Iter>
bar(Iter first, Iter last);
bar(nullptr_t);
};
}
\rSec2[bar.construct]{Constructors}
\begin{itemdecl}
bar(int a, int b);
template <typename Iter> bar(Iter first, Iter last);
bar(nullptr_t);
\end{itemdecl}
The itemdecl may, but is not required to, use a linebreak after the template head.
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.
Among others, these directives also define the following terms (note capitalization):
- "International Standard" (standard issued by ISO or IEC); use the phrase "this International Standard" when referring to the C++ standard from within the document itself, in particular when contrasting with earlier revisions of C++ or with C. When referring to the standard as a body of text, for example when explaining the general structure, prefer "this document" (encouraged by recent ISO Directives).
As a general rule, formatting macros should describe the semantics, not the desired visual outcome. For example, \textit is discouraged over \placeholder or \grammarterm.
- \cv{} renders as cv (denoting a possibly empty set of cv-qualifiers)
- \cvqual{cv1} renders as cv1 (see cv)
-
$\tcode{T}_i$ to refer to an indexed type "Ti", for example the i-th type in a parameter pack. Example: [func.bind.bind] -
$i^\text{th}$ to spell "i-th" (see #653 and #2000) - For comma-separated lists in math mode, use \dotsc to render "...". Use \ldots or \vdots (vertical dots) in other contexts. For expansion of fold expressions and other such non-comma cases, centered dots \cdots are available, too. See #2032.
- Use \tcode{inline} and \tcode{public} only when referring to syntax, not when discussing properties or attributes of functions in general. (For example, member functions defined in the class definition are implicitly inline even when not declared with the inline keyword.)
- Section headings are sentence case, not title case.
- "[ Note:" and "[ Example:" are not considered to begin a sentence, so the following word should be capitalized as the start of a sentence. Likewise, footnotes should be complete sentences or at least sentence fragments, and should be capitalized as such.
- For technical terms defined by the C++ standard, where "nonX" is either not an English word or not one with the right meaning, use a hyphen: non-abstract, non-class, non-const, non-constant, non-empty (when referring to empty classes), non-member, non-trivial (when referring to special member triviality).
- For plain English words where the "nonX" form is well-established (when the closed form is listed in a common dictionary), do not use a hyphen: nondeterministic, nonempty (when referring to sets), nontrivial (when referring to the difficulty of doing something), and nonzero.
- For plain English words where the "nonX" form is not established, use a hyphen: non-graphic, non-portable.
- Use "well-formed" (with hyphen; its use in the standard is as a self-contained adjective and never as an adverb + past participle combination)
- Avoid special characters in stable names. Full stops are fine and should be the primary means of structuring. Underscores look awkward in our current font and are best avoided.
- Try not to make stable names too long and complex. They should be recognisable and unique, but some amount of abbreviating is fine (e.g. "mem.res.cons" instead of "memory.resource.constructors").
- Use "header-name.syn" for synopses of headers (decided in #1991).
- Do not use the tilde (non-breaking space) in index entries. Decided in #1064.
The usual way to present lists is via itemize environments. Nested lists are common, though we should try hard to minimize nesting depth. In rare cases, an enumerated list may be used when the ordering of list items is relevant and cannot be expressed in other ways, though most orderings can be expressed as an ordinary list with connective words like "then".