Comment Structuring
Comment “structuring” refers to the way that comments are laid out, organized, or “structured” in relation to code, each other, and the available space on screen. Good comment structuring is key to making sure that comments can be most effectively read and maintained. The following sections cover how to effectively structure comments:
- MAJOR and Minor Comments
- Effective MAJOR Commenting
- Use MAJOR Comments for Quick Scannability [DS1] [WHERE]
- Use MAJOR Comments to Summarize Blocks of Code [DS2] [WHAT]
- Use MAJOR Comments to Both Summarize and Communicate Intent [DS3] [WHAT] [WHY]
- Keep MAJOR Comments to a Single Line [DS4]
- Use MAJOR Comments Within Nested Block Scopes [DS5] [WHAT] [WHERE]
- Precede Most MAJOR Comments with a Blank Line [DS6]
- Consider Using MAJOR Comments to Divide Longer Data Types into Clear Sections [DS7] [WHAT] [WHERE]
- 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] [WHERE]
- Effective Use of Space
