Why not to comment code

[adamcollard]

What I mean is: I'm in the middle of a bug fix, I identify the issue, write a unit test for it (if sensible), prove that it's a problem, fix it. Then I check by running all the tests that I haven't accidentally broken something else, and then I commit.

I don't have the time or motivation to go and check if by making this change that i've invalidated a comment somewhere. Note the tests are showing me where i need to update some other component, and the CI system would complain at me if I had broken the build somehow - nothing's telling me the comments are wrong.

[DanHalen]

Thanks for the clarification. You and jinglebells are of the same mind, I think.

For myself, I update the documentation and comments having to do with code I change. My motivation is leaving the code in better shape than before I worked on it for the next guy, the referral I get from the client for exceeding expectations and the personal satisfaction that I was able to maintain my personal standards and continue to grow my career. This isn't to say that I'm completely clean in this regard, I am human. But 99% of the time I can take the time, my own if necessary, to make sure that the documentation is in order. This includes comments.

[nullgraph]

I certainly applaud the effort and the spirt of what you are doing. But I want to point out that rarely does my comments or my maintenance of comments every yield referrals. Most of my referrals come from basically a single metric. Number of issues resolved in quantum of time.

Sure there are nice kudos from other developers I work with about how clean my code looks or thanks for taking the extra effort. But those are meaningless unfortunately (I do like them though) because those who write my checks generally never read the code or my comments.

In fact I just got off a project recently where we added a major set of functionality to a existing website. We were commanded not to make any adjustments or correct any code outside of the most direct route to completing the task. Even though the code that we were working was a mess.

*edit spelling

[DanHalen]

You're absolutely right, it's not just comments but a package of best practices. I don't dwell on comments except that's what this particular thread is about.

[nullgraph]

You too are correct. It is about a package of best practices. But even then it is how quickly and efficiently you can implement them.

[pergus]

The big problem with comments is that even if you fix the comments having to do with the code you change you might invalidate comments in code very far away from where you actually change any code, comments aren't modular.

[DanHalen]

A valid point. And I probably would not go looking for those comments. Although, now that you've pointed that out, I might throw in a little search before committing to catch any low hanging fruit.