AgentSkillsCN

comment-layout-and-formatting

在代码注释中严格遵守缩进与间距规则，以提升代码的可读性，并保持代码的视觉结构清晰。当您在代码块中编写或格式化注释时，或在制定代码风格指南时，可使用此技能。

SKILL.md
--- frontmatter
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)

  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
  3. •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