Tidy Comments

Improves code comments so they are clear, accurate, and useful. Use when asked to "clean up the comments", "improve the comments", or "document this function".

tuyv Updated 1 repo stars

File contents

Tidy Comments

Good comments make code easier to understand. This skill helps you write better ones.

Principles

  • Comments should explain why, not what. The code already says what it does.
  • Keep comments short and to the point.
  • Make sure comments are accurate. An outdated comment is worse than no comment.
  • Use complete sentences with correct spelling and grammar.
  • Do not state the obvious. i++ // increment i adds nothing.
  • Remove commented-out code. Version control remembers it.
  • Write a doc comment for every public function, describing its parameters and return value.

Steps

  1. Read the file carefully and understand what it does.
  2. Think step by step about which comments are helpful and which are not.
  3. Remove comments that restate the code.
  4. Rewrite unclear comments so they are clear.
  5. Add comments where the reasoning is not obvious.
  6. Double-check your work before finishing.

Tips

  • Imagine a new teammate reading the code for the first time.
  • When in doubt, prefer a better name over a comment.
  • Be careful and thorough. Take your time.

tuyv/ccpm commit 172b4a634c

Frequently asked questions

npx get-skill add tuyv/tidy-comments