-
Notifications
You must be signed in to change notification settings - Fork 0
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 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;
// ...
};
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.