In my opinion, it strongly depends on what you’re coding.
Low-level code where you need to initialize array indices to represent certain flags? Absolutely comment the living shit out of that. → See response.
High-level code where you’re just plumbing different libraries? Hell no, the code is just as easily readable as a comment.
I do also think that, no matter where you lie in this spectrum, there is always merit to improving code to reduce the need for documentation:
Rather than typing out the specification, write a unit/integration test.
Rather than describing that a function should only be called in a certain way, make it impossible to do it wrongly by modelling this in your type system.
Rather than adding a comment to describe what a block of code does, pull it out into a separate function.
Rather than explaining how a snippet of code works, try to simplify it, so this becomes obvious.
The thing with documentation is that it merely makes it easier to learn about complexity, whereas a code improvement may eliminate this complexity or the need to know about it, because the compiler/test will remember.
This does not mean you should avoid comments like they’re actively bad. As many others said, particularly the “why” is not expressable in code. Sometimes, it is also genuinely not possible to clean up a snippet of code enough that it becomes digestable.
But it is still a good idea, when you feel the need to leave a comment that explains something else than the “why”, to consider for a moment, if there’s not some code improvement you should be doing instead.
In my opinion, it strongly depends on what you’re coding.
Low-level code where you need to initialize array indices to represent certain flags?
Absolutely comment the living shit out of that.→ See response.High-level code where you’re just plumbing different libraries? Hell no, the code is just as easily readable as a comment.
I do also think that, no matter where you lie in this spectrum, there is always merit to improving code to reduce the need for documentation:
The thing with documentation is that it merely makes it easier to learn about complexity, whereas a code improvement may eliminate this complexity or the need to know about it, because the compiler/test will remember.
This does not mean you should avoid comments like they’re actively bad. As many others said, particularly the “why” is not expressable in code. Sometimes, it is also genuinely not possible to clean up a snippet of code enough that it becomes digestable.
But it is still a good idea, when you feel the need to leave a comment that explains something else than the “why”, to consider for a moment, if there’s not some code improvement you should be doing instead.