My2Cents

Annotated Rules For

A Self-referential Standard for Coding Standard Development

version 1.1

copyright 2006 – 2007, Max A. Hinkley

 Printer Friendly

Rule Structure

1. Rules shall be complete, grammatically correct sentences, worded in the form of a requirement, a preference, or a guideline.

Reason: This rule is to promote clarity and effectiveness.

2. A requirementshall be met in all cases, without exception, and shall be denoted by the word "shall".

Reason: A standards requirement is like any other software requirement; it is an inviolate contract the developer must adhere to. These are the only fully enforceable rules.

3. A preference is a preferred practice thatshould be applied except where clear advantage is found in deviating, and shall be denoted by the word "should".

Reason: A preference lays down an expectation with some flexibility. If the developer has a good reason to violate a preference he may do so without violating a hard rule. If the reason for the violation is not obvious, or clearly documented, then those reviewing the code should call the violation into question. Acceptable justifications may be spelled out in the appendix annotations so that developers are made aware specifically when they may violate any preference. Consistent violations of one or more preferences by a developer without sound justifications should be referred to a lead. Preferences may provide a means of trying out potential requirements. If this is done, then deviations should be tracked. Any acceptable deviation might indicate that it would be a poor requirement.

4. A guideline is a suggested practice that is optional, and shall be denoted by the word "may".

Reason: A guideline offers a desirable approach, while leaving it entirely to the developers’ discretion. Guidelines are exempt from review, and require no justification for violations. They are truly just suggestions.

5. A prohibition is a special form of requirement that shall be denoted by the phrases "shall not" or "shall be prohibited".

Reason: Prohibitions are defined to aid in the prevention of phrases of mixed strength, such as “shall be avoided” or “should be prohibited”

6. An avoidance is a special form of preference that shall be denoted by the phrases "should not" or "should be avoided".

Reason: Avoidances are defined to aid in the prevention of phrases of mixed strength, such as “shall be avoided” or “should be prohibited”

7. The phrase "may not" shall be prohibited in the specification of rules.

Reason: This phrase connotes a prohibition, which is much stronger than the non-negated form; and could be a source of confusion.

Document Structure

8. 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.

Reason: A consistent structure can aid in readability and maintenance.

9. An annex shall consist of rules specific to a given language, tool, and/or team within the organization.

Reason: This allows general practice to be separated from specific situations without completely starting from scratch. If the domains interact, or their unique rule sets are reasonably small, an annex may simplify things for developers.

10. Except where otherwise noted, all rules of this standard that refer to the body, shall also apply to any annex.

Reason: An Annex is no different than a body in the character of its content.

11. The body of the standard shall consist of rules applicable to all code within the organization, whereas an annex addresses some subset.

Reason: The body is the law. All else is add-on.

12. 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.

Reason: While it may seem redundant to repeat the full text of the body in the appendix, it simplifies quick references, and stand-alone use of the appendix during reviews. Proper tool use make the redundancy a non-issue.

13. Deferring explanation to an external reference from an annotation should be avoided.

Reason: The standard should be self-contained for ease of interpretation. It may also become difficult to obtain copies of some reference material over the life of the standard.

14. The body and appendix should categorize rules under appropriate topic headings, and sub-headings, as appropriate.

Reason: These category make it easier to locate items quickly.

15. Within each heading level, the rules should be sorted with requirements first, followed by preferences, then guidelines.

Reason: Simple prioritization. Don’t make them wade through junk to find the meat.

16. A rule within an annex may grant an exemption to one or more rules within the main body.

Reason: Certain general rules may have good cause for exemption within a sub-domain, but exemptions should be carefully considered; and rules that are exempted should also be carefully re-examined for general validity.

17. 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.

Reason: This requirement offers structural suggestions which might be adopted if suitable to the organization.

18. An annex may incorporate the main-body rules, to synthesize a main-body of a new separate standard for the annexes audience.

Reason: In some cases, it may be simpler for all to create an entirely separate standard for the sub-domain in question.

Rule Content

19. The body shall contain rules prohibiting source language constructs that can be reasonably expected to result in unsafe, non-deterministic, or unbounded functionality.

Reason: This one is pretty self-evident; but somewhat subjective. It should not be used as an excuse to eliminate constructs that are merely unpopular.

20. The body shall contain no tutorials, or how-to programming advice. This specifically does not prohibit such information from an appendix dedicated to that purpose.

Reason: K.I.S.S. – If the developers need training, then train them; but not in the body of rules.

21. The body should contain rules requiring strict compliance with the standard source language definition.

Reason: Non-standard language constructs can make it difficult to apply automated tools that weren’t originally considered. They can also be confusing to developers who are not expert in the specific compiler suite.

22. The body should contain rules specifying the required content and layout of file header comments.

Reason: Most organizations have requirements for the specific content of the header comments. This rule helps to ensure consistent layout for ease of reading.

23. The body should contain rules prohibiting the use of source language constructs that are undefined or implementation defined.

Reason: These language constructs can affect portability, but more importantly can lead to unexpected results when used by developers who are not expert in the specific compiler suite. They can also make the application of automated analysis tools more difficult.

24. The body should contain rules for avoidance of source language constructs that are reasonably expected to be a source of ambiguity for human readers.

Reason: Ambiguity is quite subjective, and might best be left to reviewers in most cases. Don’t have too little faith in the comprehension of your developers; and don’t use this as an excuse to eliminate things on the basis of popularity.

25. The body should contain style rules stating preferences for readability and consistency.

Reason: Style rules are essential; but style is almost entirely subjective. As style rules tend to be language specific, they may also be placed in an annex. Style also includes the avoidance or promotion of the use of constructs for any reason not covered under previous rules. This may include rules on popular or unpopular ways of doing things (e.g. use of “break”, “goto”, and multiple “returns”; these things are not unsafe or ambiguous, but are often considered undesirable for stylistic reasons; don’t promote them to something they are not).

26. Style rules should not be stated as requirements or prohibitions.

Reason: This rule amplifies the “preferences” of the previous rule. As necessary as style rules are; there may be very good reasons to break them in limited circumstances. Doing so may improve readability, performance, or even functionality. They should almost always be stated as preferences, though breakage for some may be held to a high standard of justification. In limited circumstances, even the dreaded “goto” can be a very good thing.