I constantly see people making the claim that "comments tend to become outdated." The thing is, I think I have seen maybe two or three outdated comments my entire career. Outdated information in separate documents happens all the time, but in my experience outdated comments in the code itself are exceedingly rare.
Have I just been lucky in who I work with? Are certain industries more prone to this problem than others? Do you have specific examples of recent outdated comments you've seen? Or are outdated comments more of a theoretical problem than an actual one?
Best Answer
Constantly
I really can't believe I'm the only one swimming in outdated and misleading comments. In the off chance this helps with understanding:
It probably depends most importantly on the age of the code. The next factor would be turnover on the staff.
I do equal parts R&D and maintenance work. The R&D is new code, generally stuff that's a little off the beaten path. Many of my colleagues believe in putting in a lot of commented explanation when trying something that there isn't a library already out there for. Since the comment to code ratio is higher than normal there's just more opportunities for things to go out of sync.
The maintenance code...I'm an active maintainer on a system that is over 10 years old and another that is over 5. The 10 year old code and comments are atrocious, as you'd expect. Over 10 years you get a lot of hands in the codebase and no one has any idea how the whole thing works anymore. The 5 year old code and comments are pretty good because the turnover on the team has been pretty low.
I work almost all services, even our products are highly customized to a particular customer.
Specific examples:
Comments describing the performance improvement for a particular methodology, like avoiding an in-memory copy. A big deal when a top end machine in a Pentium 2 with MBs of RAM, but hardly a problem now.
TODOs
Blocks of copy-pasted code including comments. Comment may have made sense in its original location, but hardly makes sense here
Comment blocks on top of commented out code (Who knows how many years that's been in there).
In all these you see a trend of just not maintaining the comments and code at the same level as the software. IDEs and basic developer habits don't help with this, my eye has been trained to speed past them. I think comment outdated-ness is relatively cheap to avoid in green-field and active projects. If you can keep the code/comment ratio high, it's not a big deal to keep them up to date. It's a little harder to justify hunting these things down when you're budgeted x hours for a bug fix on a production system.