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.
I don’t think they’re lazy, I think they’re not good writers. Not being able to write well is very common among programmers (not having to communicate with written language is one reason a lot of people go into coding) and in my experience the Venn diagrams for “not a good writer” and “thinks comments are unnecessary” overlap perfectly.
And isn’t it such a dangerous overlap! The coder whose writing (in their native language) is unclear, repetitive, convoluted, or hard to follow too often produces code with the same qualities. It’s even worse when the same coder believes “code is self-documenting” without considering why. Code self-documents with careful and deliberate effort, and in my experience, it is the really good writers who are most capable of expressing code in this way.
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.
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.
I’ve never had a manager that was even aware of the comments vs. no comments issue. If I ever had, I would have just told them that a lack of comments makes the original coder harder to replace.
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 <variable name>, or this does <method name>”. 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.
I get what you’re saying. Perhaps I just haven’t had too many variables and such that have had such comments. VsCode shows the comments on hover when you’re in other parts of the code base. Which makes most any comment useful because something that is obvious in one part of the code isn’t immediately obvious in another. Though, that necessitates making comments that actually help you figure that out.
I had a old job that told me that code is “self documenting” if you write it “good enough”. And that comments were unnecessary.
It always annoyed the heck out of me. Comments are imo more helpful than hurtful typically.
Is it just me? Or am I weird? Lol.
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.
I don’t think they’re lazy, I think they’re not good writers. Not being able to write well is very common among programmers (not having to communicate with written language is one reason a lot of people go into coding) and in my experience the Venn diagrams for “not a good writer” and “thinks comments are unnecessary” overlap perfectly.
And isn’t it such a dangerous overlap! The coder whose writing (in their native language) is unclear, repetitive, convoluted, or hard to follow too often produces code with the same qualities. It’s even worse when the same coder believes “code is self-documenting” without considering why. Code self-documents with careful and deliberate effort, and in my experience, it is the really good writers who are most capable of expressing code in this way.
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.
I’ve never had a manager that was even aware of the comments vs. no comments issue. If I ever had, I would have just told them that a lack of comments makes the original coder harder to replace.
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
Docstring are user documentation, not comments. User documentation, with examples (tests), is always useful.
As long as it’s maintained. Wrong documentation can often be worse than no documentation.
Code is the what. Comments are the why.
Few things worse than an out of date comment.
Have you ever worked in a place where every function/field needed a comment? Most of those comments end up being “This is the <variable name>, or this does <method name>”. 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.
And a good IDE let’s you hide it so… what is your point?
The issue with having mandatory useless comments is that any actually useful comments get lost in the noise.
I get what you’re saying. Perhaps I just haven’t had too many variables and such that have had such comments. VsCode shows the comments on hover when you’re in other parts of the code base. Which makes most any comment useful because something that is obvious in one part of the code isn’t immediately obvious in another. Though, that necessitates making comments that actually help you figure that out.