Comments as communication
I often hear that code should be "self-documenting".
Instead of writing a comment, you should create a function or class with that name instead.
Whilst I agree with this, I think that code comments shouldn't describe what the code is doing - they should explain why the code is needed and provide any additional context to the person reading it.
If a comment just says Returns true or Sends an email, that can be understood by reading the code, so isn't providing any extra value or context. They can also become outdated as the code changes.
If a line of code is needed to fix a certain state or situation, or if a piece of code isn't particularly readable and isn't obvious what it does, those are good times to add comments.
- Oliver
