Commenting for Maintenance Programmers
Beyond what has already been covered in this training, there are several additional items to be aware of when crafting documentation to set up maintenance programmers for success. The following sections cover different kinds of comments important for maintenance programmers:
- Documenting Intent
- Document What the Code Is Intended To Do [DP1]
- Document Design Intent As A Programmer [DP2]
- Document the Non-Obvious [DP3]
- Document Workarounds [DP4]
- Document Intentional Decisions For Code That Would Break If Changed/Removed [DP5]
- Justify Deviations from Good/Standard Programming Practices [DP6]
- Justify Extra Code [DP7]
- Document Rationale for Levels of Flexibility [DP8]
- Document Why Values Are Chosen
- Document Commented-Out Code...If Absolutely Necessary [DP11]
- Documenting Technical Debt with TODOs [DP12]
- Document Performance Considerations [DP13]
- Document Algorithm/Spec References [DP14]
, multiple selections available,