Spamming comments is rather controversial, especially in high-level languages. Problem is, they only show up in one place, so they’re just not very useful, but also have a high chance of becoming inaccurate over time. In particular when you spam them to explain relatively trivial stuff, people will stop reading them, meaning they won’t update them.
The ‘what’ can be documented with meaningful variable/function names, log/error/assert messages and perhaps most importantly unit/integration tests (which should be understood like a specification that checks automatically that it’s applied correctly).
Comments are indispensible for explaining the ‘why’, though, whenever that is not obvious.
Yeah, there’s a balance. If you comment every row of your code, you aren’t naming things clearly. If you never comment, the context is always incomplete.
“Clearly” is also subjective. What might be perfectly clear to me reading my own code may be really confusing to someone else, and vice versa. Especially if the person reading the code isn’t as familiar with the language as the person who wrote it, or if the code is using some syntactic sugar that isn’t super common, or plenty of other reasons.
Spamming comments is rather controversial, especially in high-level languages. Problem is, they only show up in one place, so they’re just not very useful, but also have a high chance of becoming inaccurate over time. In particular when you spam them to explain relatively trivial stuff, people will stop reading them, meaning they won’t update them.
The ‘what’ can be documented with meaningful variable/function names, log/error/assert messages and perhaps most importantly unit/integration tests (which should be understood like a specification that checks automatically that it’s applied correctly).
Comments are indispensible for explaining the ‘why’, though, whenever that is not obvious.
Yeah, there’s a balance. If you comment every row of your code, you aren’t naming things clearly. If you never comment, the context is always incomplete.
You don’t comment what something does, ir can clearly be seen from the code itself. You comment why you do it.
“Clearly” is also subjective. What might be perfectly clear to me reading my own code may be really confusing to someone else, and vice versa. Especially if the person reading the code isn’t as familiar with the language as the person who wrote it, or if the code is using some syntactic sugar that isn’t super common, or plenty of other reasons.
True. It’s more like there’s no need to comment an if statement with “checks if a is larger than b”
Yes, that would be the context I’m talking about