Code Comments

The whole "no comments" thing can be taken too far. We should strive to write code that is clear as possible so comments aren't necessary.

However, the act of writing a function header before writing the function is a good way to think about the intent of the code your about to write.

If you try to write a concise description of a function and you struggle with it, then its a sign your design might be over complex,or you haven't decomposed the problem well enough.

Its also a good way to spot violations of SRP.if you find that you have to use the word "and" multiple times to describe the intent of a function, then you probably have multiple functions crammed Into one.

After refactoring your code, perhaps using TDD, if your comment is completely redundant because the code expresses everything you need to know, then as a last step you should delete the comment.

Here's what I consider bad comments:

1. Comments that add no value because the code already expresses intent more clearly than the comment.

2. Comments that are out of sync with the code.

3. Code block comments that would be better written as a function name.

Writing clean code takes discipline. The act of writing intent before the code helps you clarify in you mind the design, and is a valuable design tool.

The most valuable comments are ones that describe the why. Comments that describe the what are the dangerous kind.