AgentSkillsCN

writing-effective-comments

遵循“软件设计哲学”中的原则，编写高效的代码注释。适用于代码文档化、注释审查，或优化现有文档时。

SKILL.md
--- frontmatter
name: writing-effective-comments
description: Write effective code comments following principles from "A Philosophy of Software Design". Use when documenting code, reviewing comments, or improving existing documentation.

Writing Effective Comments

When to Use This Skill

  • •Writing documentation for new code
  • •Reviewing or improving existing comments
  • •Documenting interfaces, classes, or modules
  • •Adding implementation comments for complex logic
  • •Learning language-specific documentation conventions

The Golden Rule

Comments should describe things that are not obvious from the code.

If a comment repeats what the code already says, it adds no value. Good comments capture information that exists only in the developer's mind: rationale, intent, constraints, and design decisions.

Quick Reference

NeedGo To
Core principles of good commentsphilosophy.md
What to avoid (bad patterns)antipatterns.md
Practical workflow for writing commentsworkflow.md
Documenting interfaces/APIsinterface_comments.md
In-code implementation commentsimplementation_comments.md
Good vs bad examplesexamples.md

Language-Specific Conventions

LanguageConventionGuide
JavaScript/TypeScriptJSDocconventions/jsdoc.md
RubyYARDconventions/yard.md
Gogodocconventions/godoc.md
Rustrustdocconventions/rustdoc.md
ElixirExDocconventions/exdoc.md

Comment Types at a Glance

Interface Comments (What and Why)

Document the abstraction for users who won't read the implementation:

  • •What does it do? (high-level purpose)
  • •What do parameters mean? (not just types)
  • •What does it return? (semantic meaning)
  • •What side effects occur?
  • •What can go wrong?

Implementation Comments (How and Why)

Explain non-obvious code for future maintainers:

  • •Why was this approach chosen?
  • •What's the algorithm doing at a high level?
  • •What constraints or edge cases matter?
  • •What would break if this changed?

Core Principles Summary

  1. •Write comments first - Document before implementing to clarify thinking
  2. •Use different words - Comments at a different abstraction level than code
  3. •Capture intent - Code shows what, comments explain why
  4. •Keep close to code - Comments near the code they describe stay accurate
  5. •Review comments - Treat comment quality as seriously as code quality