A Self-referential Standard for Coding Standard Development

version 1.1

copyright 2006 – 2007, Max A. Hinkley

 

Rule Structure

    1. Rules shall be complete, grammatically correct sentences, worded in the form of a requirement, a preference, or a guideline.
    2. A requirement shall be met in all cases, without exception, and shall be denoted by the word “shall”.
    3. 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”.
    4. A guideline is a suggested practice that is optional, and shall be denoted by the word “may”.
    5. A prohibition is a special form of requirement that shall be denoted by the phrases “shall not” or “shall be prohibited”.
    6. An avoidance is a special form of preference that shall be denoted by the phrases “should not” or “should be avoided”.
    7. The phrase “may not” shall be prohibited in the specification of rules.

Document Structure

    1. 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.
    2. An annex shall consist of rules specific to a given language, tool, and/or team within the organization.
    3. Except where otherwise noted, all rules of this standard that refer to the body, shall also apply to any annex.
    4. The body of the standard shall consist of rules applicable to all code within the organization, whereas an annex addresses some subset.
    5. 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.
    6. Deferring explanation to an external reference from an annotation should be avoided.
    7. The body and appendix should categorize rules under appropriate topic headings, and sub-headings, as appropriate.
    8. Within each heading level, the rules should be sorted with requirements first, followed by preferences, then guidelines.
    9. 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.
    10. A rule within an annex may grant an exemption to one or more rules within the main body.
    11. An annex may incorporate the main-body rules, to synthesize a main-body of a new separate standard for the annexes audience.

Rule Content

  1. The body shall contain rules prohibiting source language constructs that can be reasonably expected to result in unsafe, non-deterministic, or unbounded functionality.
  2. 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.
  3. The body should contain rules requiring strict compliance with the standard source language definition.
  4. The body should contain rules specifying the required content and layout of file header comments.
  5. The body should contain rules prohibiting the use of source language constructs that are undefined or implementation defined.
  6. The body should contain rules for avoidance of source language constructs that are reasonably expected to be a source of ambiguity for human readers.
  7. The body should contain style rules stating preferences for readability and consistency.
  8. Style rules should not be stated as requirements or prohibitions.