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.
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.
Yes, that would be the context I’m talking about