4 ms·
While I agree to some extent, the problem with comments is that they need to be maintained in order to be helpful: code comments - updated when the code changes
by atomashpolskiy 6y ago
While I agree to some extent, the problem with comments is that they need to be maintained in order to be helpful: code comments - updated when the code changes, general comments - when the context changes, etc. This is a work in itself: developer has to remember to do it, reviewer has to remember to look for it. In my experience, people tend to forget to do it or just don't bother, which means that someone else finds himself with a contradictory, outdated, confusing comment further down the road.
- bluefirebrand 6y agoSure but which is more likely: Someone updating the comments in code that they are updating because they see the comments right in front of them. Or Someone going to look through the documentation to see if there is anything relevant about the code they are working on that needs to be updated.
- atomashpolskiy 6y agoSomewhat surprisingly, it depends. For instance, in our case application support is responsible for/interested in the documentation, and they make sure that developers create/update the relevant documentation for each of the release items. Stale comments, on the other hand, need to be identified and addressed in code reviews, and in practice we're not always good at that.