majiayu000 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