Description
2 Take inspiration from MISRA and CERT
2.1 Good, Bad Example => Compliant, Non-Compliant Example / Antipattern
2.2 Change “recommendation” to categories. Categories could be Advisory, Required, Mandatory, maybe Disapplied. Not sure what the difference between Required and Mandatory is or if it's necessary.
2.2.1 Allow mostly only => stricter, but advisory could be loosened
3 Tightness of guidelines
3.1 “guidelines” seems to imply they are not optional
3.2 Good to use certain phrases to avoid wiggle-room
4 Examples tips
4.1 Compliant vs Non-Compliant Examples
Skirting the line on the non-compliant example helps to show where the line is.
4.2 Formatting background color of examples
Compliant => Blue
Non-Compliant => Red
To avoid fast copy-pasting of non-compliant examples.
4.3 Make sure only one thing non-compliant per example
To make clearer the issue make sure the whole example complies, except for the bit that we want to highlight.
5 Numerical Prioritization of Guidelines
Helps those retrofitting the guidelines on top of existing code to know which parts of their codebase to prioritize.
5.1 Make it numerical with 3 categories, each with a rating
6 Categories of guidelines
Useful for broad categories.
6.1 Keep loose now, tighten later
We may find that a single category should be split into N different categories.
7 Numbering
Consider some numbering schema that’s a bit more human readable in addition to the stable IDs.
Useful for tool output.
8 Tool Coverage
8.1 Consider how you will show coverage of tools over guidelines