In.struct

In.struct: The structure of this document

Each rule (guideline, suggestion) can have several parts:

• The rule itself -- e.g., no naked new
• A rule reference number -- e.g., C.7 (the 7th rule related to classes). Since the major sections are not inherently ordered, we use letters as the first part of a rule reference "number". We leave gaps in the numbering to minimize "disruption" when we add or remove rules.
• Reasons (rationales) -- because programmers find it hard to follow rules they don't understand
• Examples -- because rules are hard to understand in the abstract; can be positive or negative
• Alternatives -- for "don't do this" rules
• Exceptions -- we prefer simple general rules. However, many rules apply widely, but not universally, so exceptions must be listed
• Enforcement -- ideas about how the rule might be checked "mechanically"
• See alsos -- references to related rules and/or further discussion (in this document or elsewhere)
• Notes (comments) -- something that needs saying that doesn't fit the other classifications
• Discussion -- references to more extensive rationale and/or examples placed outside the main lists of rules

Some rules are hard to check mechanically, but they all meet the minimal criteria that an expert programmer can spot many violations without too much trouble. We hope that "mechanical" tools will improve with time to approximate what such an expert programmer notices. Also, we assume that the rules will be refined over time to make them more precise and checkable.

A rule is aimed at being simple, rather than carefully phrased to mention every alternative and special case. Such information is found in the Alternative paragraphs and the Discussion sections. If you don't understand a rule or disagree with it, please visit its Discussion. If you feel that a discussion is missing or incomplete, enter an Issue explaining your concerns and possibly a corresponding PR.

Examples are written to illustrate rules.

• Examples are not intended to be production quality or to cover all tutorial dimensions. For example, many examples are language-technical and use names like f, base, and x.
• We try to ensure that "good" examples follow the Core Guidelines.
• Comments are often illustrating rules where they would be unnecessary and/or distracting in "real code."
• We assume knowledge of the standard library. For example, we use plain vector rather than std::vector.

This is not a language manual. It is meant to be helpful, rather than complete, fully accurate on technical details, or a guide to existing code. Recommended information sources can be found in the references.