A Taxonomy of Comments Or a Critique of C and OS Code Through Comments Yoann Padiolean and Lin Tan September 10, 2008 Contents 1 Overview 4 2 Meta Information() 7 3 Past and Future() 10 3.1 Todo() . 10 3.2 Reminder() . 11 3.3 Trigger, deprecated and obsolete() . 13 3.4 OldCode() . 14 3.5 Log() . 15 4 Explanation() 17 4.1 Example() . 17 4.2 Specific Explanations() . 17 4.2.1 For Explanations() . 18 4.2.2 Bit Explanations() . 20 4.2.3 List Explanations() . 20 4.3 Other specific explanations() . 20 4.4 ShortNameExlain () . 20 4.5 Ref() . 21 4.6 Diagram() . 21 4.7 Font() . 23 4.8 Other . 25 4.8.1 Brief . 25 4.8.2 Summary . 25 4.8.3 Long . 25 5 Type() 29 5.1 NULL() . 29 5.2 Bound() . 31 5.3 Range() . 31 5.4 Unit() . 32 5.5 State type() . 33 5.6 Region pointers() . 33 5.7 Dependent types() . 34 5.7.1 Array dependent types() . 34 5.7.2 Union dependent types() . 34 5.8 Relation types() . 35 5.9 Memory types() . 36 5.10 Bit and bytes() . 36 1 5.10.1 Bitset . 36 5.10.2 cpplint . 37 5.10.3 Group . 37 5.10.4 Devil . 38 5.11 Polymorphism, template types() . 41 5.12 Shape . 41 5.13 Abuse int(), Abuse string() . 41 5.14 Not seen in comments . 41 6 Interface() 42 6.1 Pre conditions() . 42 6.2 InOut() . 43 6.3 Context() . 45 6.3.1 Context Lock() . 45 6.3.2 Context Caller() . 49 6.3.3 Context Interrupt() . 49 6.3.4 Other context . 50 6.3.5 SmPL . 52 6.3.6 Buffer Ownership() . 52 6.4 Effects() . 52 6.5 Error() . 53 6.6 Magic number() . 57 6.7 Module interface() . 59 6.8 Time and Space properties() . 60 6.9 Other interface() . 61 7 Code Relationships() 62 7.1 File organization() . 63 7.1.1 Visual organization() . 63 7.1.2 Grouping() . 64 7.2 EndOfXXX() . 65 7.3 Control Flow() . 66 7.3.1 Caller Callee() . 66 7.3.2 Before After() . 67 7.3.3 Other . 68 7.3.4 Unreached() . 69 7.3.5 ProblematicControl() and FALLTHRU() . 69 7.3.6 Else Explanation() . 70 7.4 Data Flow() . 70 7.4.1 Unused() and ARGSUSED() . 72 7.5 Other code-data correlations() . 73 7.5.1 DataClump() . 73 7.5.2 StructInitialize() . 74 7.5.3 Lock variables correlations() . 75 7.5.4 Protocol() . 77 7.6 Repeat() . 78 7.6.1 Repeat type() . 78 7.6.2 Repeat parameters() . 78 7.7 Designator() . 79 7.7.1 DesignatorField() . 80.