A Self-referential Standard for Coding Standard Development
copyright 2006 – 2007, Max A. Hinkley
- Rules shall be complete, grammatically correct sentences, worded in the form of a requirement, a preference, or a guideline.
- A requirement shall be met in all cases, without exception, and shall be denoted by the word “shall”.
- A preference is a preferred practice that should be applied except where clear advantage is found in deviating, and shall be denoted by the word “should”.
- A guideline is a suggested practice that is optional, and shall be denoted by the word “may”.
- A prohibition is a special form of requirement that shall be denoted by the phrases “shall not” or “shall be prohibited”.
- An avoidance is a special form of preference that shall be denoted by the phrases “should not” or “should be avoided”.
- The phrase “may not” shall be prohibited in the specification of rules.
- The standard shall consist of three major parts; a body, optional annexes, one or more appendices; and may also contain table-of-contents, index, or other supporting components as needed.
- An annex shall consist of rules specific to a given language, tool, and/or team within the organization.
- Except where otherwise noted, all rules of this standard that refer to the body, shall also apply to any annex.
- The body of the standard shall consist of rules applicable to all code within the organization, whereas an annex addresses some subset.
- An annotation appendix shall contain all rules of the main body, each annotated with complete justification and sufficient explanations or theory to ensure comprehension of the rule.
- Deferring explanation to an external reference from an annotation should be avoided.
- The body and appendix should categorize rules under appropriate topic headings, and sub-headings, as appropriate.
- Within each heading level, the rules should be sorted with requirements first, followed by preferences, then guidelines.
- A separate annotation appendix may be created for each annex, or alternately the annotations for all annexes and the main body may reside in a single appendix.
- A rule within an annex may grant an exemption to one or more rules within the main body.
- An annex may incorporate the main-body rules,Â toÂ synthesize aÂ main-body of a new separate standard for the annexes audience.
- The body shall contain rules prohibiting source language constructs that can be reasonably expected to result in unsafe, non-deterministic, or unbounded functionality.
- The body shall contain no tutorials, or how-to programming advice. This rule specifically does not prohibit such information from an appendix dedicated to that purpose.
- The body should contain rules requiring strict compliance with the standard source language definition.
- The body should contain rules specifying the required content and layout of file header comments.
- The body should contain rules prohibiting the use of source language constructs that are undefined or implementation defined.
- The body should contain rules for avoidance of source language constructs that are reasonably expected to be a source of ambiguity for human readers.
- The body should contain style rules stating preferences for readability and consistency.
- Style rules should not be stated as requirements or prohibitions.