Documenting Intent
“Intent” is one of the most valuable things to document that typically can’t be directly and fully communicated in code. There are many kinds of intent (some overlapping) that are important to document:
- 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]
, multiple selections available,