-
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 Use this idiom when specifying something we require a conforming implementation to do. |
|
|
"Unless it is a bit-field, a most derived object shall have a non-zero size" |
|
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"
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.
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}
- Requires: 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, where as expressions should end with a period (.).
Examples: Effects: The function works in this way. Effects: Equivalent to expr. Effects: Behaves the same as: statement; Effects: Equivalent to: statement1; statement2;
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;
// ...
};
- Template parameter names are camel-case.
- Template type parameters use
classnottypename. -
constgoes to the left of the type it modifies.
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 above, and the referencing of other standards documents.