kitchen-engineer42/pdf2skills/comment-layout-and-formatting

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)

1. Align comments with the code they describe using the same indentation level
2. Ensure comments do not obscure the visual indentation structure of the code
3. 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

1. Place at least one blank line before each comment to separate it from code
2. Optional: Use blank lines both before and after comments (two total)

• Pros: Better visual effect, easier to scan
• Cons: Consumes more display space

1. 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