Programmer Humor

Document intentions and decisions, not code.

Code should always by itself document the "how" of the code, otherwise the code most likely isn't good enough. Something the code can never do is explain the "why" of the code, something that a lot of programmers skip. If you ever find yourself explaining the "how" in the comments, maybe run through the code once more and see if something can be simplified or variables can get more descriptive names.

For me, that's what was originally meant with self-documenting code. A shame lazy programmers hijacked the term in order to avoid writing any documentation.

Its definitely a balance. Good code shouldn't need much commenting, but sometimes you have to do something for a reason that isn't immediately obvious and that's when comments are most useful. If you're just explaining what a snippet does instead of why you're doing it that way, there's probably more work to be done.

Code is not self documenting when decision trees are created based on some methodology that's not extremely obvious

I absolutely agree, and I too hate this stupid idea of "good code documenting itself" and "comments being unnecessary".
I have a theory where this comes from. It was probably some manager, who has never written a single line of code, who thought that comments were a waste of time, and employees should instead focus on writing code. By telling them that "good code documents itself", they could also just put the blame on their employees.
"Either you don't need comments or your code sucks because it's not self-documenting"
Managers are dumb, and they will never realize that spending a bit of time on writing useful comments may later actually save countless hours, when the project is taken over by a different team, or the people who initially created it, don't work at the company anymore.

Code is the what. Comments are the why.

Few things worse than an out of date comment.

Comment should describe "why?", not "how?", or "what?", and only when the "why?" is not intuitive.

The problem with comments arise when you update the code but not the comments. This leads to incorrect comments, which might do more harm than no comments at all.

E.g. Good comment: "This workaround is due to a bug in xyz"

Bad comment: "Set variable x to value y"

Note: this only concerns code comments, docstrings are still a good idea, as long as they are maintained

Have you ever worked in a place where every function/field needed a comment? Most of those comments end up being "This is the , or this does ". Beyond, being useless, those comments are counter productive. The amount of screen space they take up (even if greyed out by the IDE) significantly hurts legability.