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 iadds nothing. - Remove commented-out code. Version control remembers it.
- Write a doc comment for every public function, describing its parameters and return value.
Steps
- Read the file carefully and understand what it does.
- Think step by step about which comments are helpful and which are not.
- Remove comments that restate the code.
- Rewrite unclear comments so they are clear.
- Add comments where the reasoning is not obvious.
- 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.