Notes from the Clean Code book - 5

4 - Comments

The most valuable code is the one that does NOT need to be written
Do NOT comment incorrect code, it’s better to rewrite it
There is nothing more useful than a comment in the right place, on the other hand, there is nothing worse than incorrect comments
There is nothing more harmful than an old comment that lies and misinforms
The older and farther away is the comment from the code it describes, the more probability of it being wrong
They are a necessary evil
When a comment is written, thing if there is no other way to express it in the code
An inaccurate comment is worse than no comment
Only the code speaks truth about what it does
An useful comment is when it clarifies content that cannot be modified to be improved (as using things from external libraries)
The TODO comments are NOT an excuse to keep incorrect code
Do NOT use comments if a clear function or variable can be used instead
If a comment is written, it must describe the code around it, never information about global state
The link between a comment and the code it describes MUST be evident, if you bothered on writing the comment, the least you can do is to make sure the reader will understand its meaning
A short function requires no explanation and a good name works best than a comment in the function header

Incorrect code is the main motivation to write comments
A clear and expressive code is much better than a complex one full of comments, instead of investing time commenting the code, fix it

Those by enterprise standards, such as copyright (they are NOT legal contracts, whenever possible, refer to a standard license or an external file)

Are an excuse of poor code
Adding comments for no reason or just to follow a process are an error, if time is invested on writing comments, make sure it’s the best that can be written
Any comment that forces the reader to look its meaning elsewhere, has failed to communicate and it does not deserve the bits its using
A redundant comment that explains how the code works is an error
A confusing or inaccurate comment can be a future headache
Comments about changes (changelogs) were necessary before Version Control Software, Today are irrelevant and must be removed
Comments used as markers are appealing if they are not abused, they will be ignored otherwise. Use them when the benefit is big
```
//     Event
////////////////////////////////
```
The comments that mark the end of a function make sense on lengthy functions, try to reduce the size of the functions instead