1.9 KiB
| id | title | status | tags | date_added | url_omnivore | url_original | |
|---|---|---|---|---|---|---|---|
| 24bd8d1e-b118-4930-a86d-3929f2dad34c | The First Rule of Comments in Code | ARCHIVED |
|
2023-11-02 23:25:19 | https://omnivore.app/me/https-youtu-be-hxsx-3-vbf-qq-si-c-5-qy-m-mg-8-j-yhc-bbq-18b92ffccf6 | https://youtu.be/hxsx3vbf-QQ?si=-C5QyMMg8JYhcBBQ |
The First Rule of Comments in Code
Notes
Comments are bad by nature:
- They get outdated pretty quickly, and you don't know if the comments is updated with the code.
- A comments is most probably noise, because it's not gonna provide more information than the code itself.
- Commented code is broken code, because it's probably outdated compared to it's context.
Some rules to evade writing comments:
Code that needs a comment, needs to be rewritten. Always try to put the information in the code. if it needs a comment, it's not good enough.
Move information somewhere else. this is similar to the previous, move to a variable name, or to a documentation file in the worst case.
How quickly the information will goes out of date. It's so simple that a comments goes out of sync with the code, to prevent that transform the comment in code.
If a comment gives no more information than the code, delete it.
"I need to explain the complexity". No, you need to fix the complexity. If the complexity is so big, put in the documentation instead. A comment cannot fix complexity, and will require hard work to change that code.
Don't comment out code, delete it. Commented code goes quickly out of sync with it's context, is not tested in any way and the effort of updating it is almost the same if not higher that writing it over with better knowledge, so it's better to just delete it. If we need this code back, we can recover it with git.