3 ms·

You must be doing comments wrong. If they explain the why, they should still be relevant. Or people should rewrite them when they adjust the code...

• vidarh 13y ago
  If they explain the why, they may be justified, but they will still eventually become invalid when the code is changed to do something with a different rationale. And yes, people should rewrite them when they adjust the code, but like so many other things: In any reasonably large code base it sooner or later gets neglected because the code still runs and passes all tests without it. If you want "documentation" that will stay up to date, you either need an extremely rigorous development process, which pretty much nobody has, or your documentation needs to be in the form of test cases that will break when the documentation is no longer valid. I 30+ years of writing code, I've don't think I've ever come across a project of any reasonable size that haven't had substantial comments that were outdated. I would love to see such a beast - it'd be a little bit like encountering a unicorn.