DEV Community

Discussion on: I love to document my code. Am I doing it wrong?

Collapse
 
martinhaeusler profile image
Martin Häusler • Edited

Commenting code isn't "wrong" per se but (the following applies to per-line comments; API doc is a different matter entirely):

  • ... you may be better off spending your time in finding good variable and function names, and keeping your control flow and APIs clean. You will get a much better return on your time investment.

  • ... they go out of sync with the code extremely fast. Especially when multiple people work on the same code base. Comments rarely ever get updated.

  • ... they add a lot of visual noise, in particular if they just repeat in "natural language" what the code is doing and should be expressing on its own anyways. It's just like with tests: having a super-huge test suite won't add any value if the contents are useless. Having each line commented won't help if the comments don't add any info.

When I'm writing a particularly challenging piece of code, I find myself writing more line-by-line comments than usual. I try to put my reasoning in there for why I did things the way they are, such that I (or a coworker) can pick up this piece of code more easily in the future in case a modification needs to be made to it.

As stated earlier, API docs are a different matter entirely. I'm convinced that every public API member (method, class, constant...) should be documented rigorously and without exceptions. In practice, this corner is often cut due to time constraints - which makes proper naming and a clean API all the more important, because often times that is all you have to go by.