| name | comment-layout-and-formatting |
| description | Apply proper indentation and spacing rules to code comments to enhance readability and maintain code visual structure. Use when writing or formatting comments within code blocks, or when establishing code style guidelines. |
Comment Layout and Formatting
Apply these rules to ensure comments enhance rather than disrupt code readability.
Comment Indentation
When to apply: When writing or formatting code comments (excluding end-of-line comments)
- Align comments with the code they describe using the same indentation level
- Ensure comments do not obscure the visual indentation structure of the code
- Maintain visual hierarchy to help readers understand program logic structure
Rationale: Research (Shneiderman 1980) shows comments that interfere with visual scanning reduce their effectiveness. Good comment style should enhance, not disrupt, visual structure.
Comment Spacing
When to apply: When separating code blocks or emphasizing comments
- Place at least one blank line before each comment to separate it from code
- Optional: Use blank lines both before and after comments (two total)
- Pros: Better visual effect, easier to scan
- Cons: Consumes more display space
- Decision is primarily aesthetic unless display space is extremely limited
Core principle: Having a consistent convention is more important than the specific details of the convention.
Result
- Code logical structure remains clearly visible
- Comments are visually separated from code
- Comments align with their corresponding code blocks
