Crafting Documentation for Maintainability
High-quality documentation is essential for a durable and maintainable codebase. Through this training, you will learn how to craft high-quality documentation - through comments in the code - to support a codebase that is readable and a joy to work in over the long-term. The tips in this training have been tested and refined over numerous years, supplemented with many concrete code examples, and cover both how to write comments that are both maintainable themselves and support a maintainable codebase.
- The Importance of Code Documentation
- Different Purposes for Comments
- Avoiding Wasteful Comments
- Commenting at the Appropriate Level of Abstraction
- Written Communication
- Comment As You Code
- Comment Structuring
- MAJOR and Minor Comments
- Effective MAJOR Commenting
- Use MAJOR Comments for Quick Scannability [DS1]
- Use MAJOR Comments to Summarize Blocks of Code [DS2]
- Use MAJOR Comments to Both Summarize and Communicate Intent [DS3]
- Keep MAJOR Comments to a Single Line [DS4]
- Use MAJOR Comments Within Nested Block Scopes [DS5]
- Precede Most MAJOR Comments with a Blank Line [DS6]
- Consider Using MAJOR Comments to Divide Longer Data Types into Clear Sections [DS7]
- Format Plural Versions of Acronyms/Abbreviations in MAJOR Comments for Readability [DS8]
- Effective Minor Commenting
- Effective MAJOR Commenting
- Combining Comments
- Commenting Control Structures
- Place Comments Close to the Code They Apply To
- Keep Comments Close to the Corresponding Code [DS19]
- Consider Documenting Blocks of Code Rather than Individual Lines [DS20]
- Intersperse Comments with Individual Lines If That Eases Comprehension [DS21]
- Don’t Have Blank Lines Between Comments and the Code They Apply To [DS22]
- Leverage Re-usable Documentation Techniques for High-Level Documentation [DS23]
- Effective Use of Space
- MAJOR and Minor Comments
- Commenting Code Interfaces
- Namespaces/Packages
- Files/Modules
- Data Types
- Functions
- Variables
- Documenting Variables Based on Scope
- Documenting Specific Kinds of Data
- Documenting Constants [DI27]
- Make Meanings of Booleans Clear [DI28]
- Document the Meanings of “Unpopulated” Values [DI29]
- Document Values with Special Meanings [DI30]
- Document Ranges of Numeric Values [DI31]
- Document Units of Numeric Data [DI32]
- Document Data Formats That Cannot Be Concisely Captured in Names [DI33]
- Document Specifics of Filesystem Paths [DI34]
- Document Time Zones for Dates/Times [DI35]
- Document Bit-Level Details For Packed Data [DI36]
- Commenting 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]
- Documenting Intent
- Comment Maintenance
, multiple selections available,