- Martins' tone in this chapter suggests that all comments are bad and the only good comments are the ones that don't exist.
- Most of the time the code should explain itself, and shouldn't need code to accompany it.
- Examples of bad comments:
- Redundant comments, that takes longer to read than the code.
- Noise comments, comments that restate the same information as the code.
- Comments that explain what the code does, usually become outdated because the developers change the code but not the comments.
- Commented out code, since we have version control we can look back on previous commits.
- If you do need to comment:
- Contents should relate to the context of the file, instead of external variables.
- Keep the comments focused on the code rather than preferences or opinions.
- If code doesn't make sense, make sure to refactor it, instead of adding a comment.
- ToDos, IDEs can have plugins that can clean those up.
- Remove comments that has been used for debugging purposes before committing to a repository.