Are outdated comments an urban myth?

Question

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?

Answer 1

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.

Answer 2

"comments tend to become outdated."

I have seen this happening often enough to know this can be a problem.

The thing is, I think I have seen maybe two or three outdated comments my entire career.

I believe it should be perfectly possible to work in an environment where everybody takes enough care of the comments and maintains them. It's just a small extra effort to look at comments near the code you are editing and update them when appropriate. In case the comments are so far away that you don't immediately notice them, they were bad comments anyway, and shouldn't have been added in the first place (or at least not there).

Furthermore usually along with the statement that comments tend to become outdated, follows the statement that this reduces readability and confuses people. This is something which I haven't experienced yet. Every time I encounter an out of date comment, I clearly see what changed and just update the comment accordingly to represent the newer code, albeit with some extra effort.

---

A recent study by Roehm et al. 2012 observes the following:

21 participants [out of 28] reported that they get their main information from source code and inline comments whereas only four stated that documentation is their main source of information.

This is in line with your suspicion that comments in the code itself generally are still considered to be very useful. This indicates that a clear line should be drawn between outdated documentation and outdated comments.

_{Roehm, T., Tiarks, R., Koschke, R., & Maalej, W. (2012, June). How do professional developers comprehend software?. In Proceedings of the 2012 International Conference on Software Engineering (pp. 255-265). IEEE Press.}

Answer 3

Outdated comments are a job smell. It's like having outdated or neglected unit tests - it shows that the good processes that were once active at the shop are degenerating into cowboy coding. The proper "engineering culture" of taking the time to do things properly has broken down. The project/company is likely going into technical debt.

In short, yes, you've been lucky. If you happened to have a string of reasonably well-run shops so far in your career, it's quite possible not to see this much. But in more typical, less well run shops, this runs parallel to the rest of the chaos.

Answer 4

Comments are like tests, they are very good when they are up to date, but can make it even harder to understand the code if there are not.

If you never seen any outdated comments, you have been very lucky.

Most code bases I have worked with has been full of outdated comments, and usually I disregard comments completely as they usually are source of confusion instead of help.

Answer 5

Outdated comments often appear in JavaDoc:

• Listing arguments that no longer exist
• Not explaining all arguments (the missing ones were probably added later)
• Similar things for exceptions, etc.

Additionally, sometimes comments state things such as "do this here for performance" when most performance considerations tend to get stale even quicker than the code itself.

Answer 6

I do not see too many descriptive comments getting out of date, but I do see plenty of TODO comments that have been there for years. I wish they were like time capsules and said something like this:

//TODO: In 15 years AND NO SOONER... actually implement this method.

Answer 7

I deal with outdated comments from time to time. It certainly is not an urban myth. People mention it in lists of worst practices not because it hits you very often but because when it does, it's usually costs you a lot of time and effort.

In our codebase most outdated comments are caused by the use of the (anti)pattern of describing method behavior near its call and not near method declaration. It happens when someone extracts long piece of code into a method which is only called once at the moment and then comments the method call. So you end up with something like this:

featureList = GetFeatures();

// Sorting features and deleting empty ones from the list...
ProcessFeatures(featureList);

And the method is declared somewhere below without comments. People mess with these methods over the years dealing with changes of spec and fixing bugs, and eventually you end up with a method that doesn't sort the list and throws an exception when it finds the empty feature. So the comment above is an outdated comment which will eventually cost you some time in debugger. These do happen in some codebases.

Answer 8

Ask yourself this. Have you ever changed a line of code and not changed the associated comments or added new ones?

I have worked with a lot of legacy code and the comments are sometimes not even close to relevant.

Answer 9

For the most part, my experience matches yours but I have run across one case where that was true all over the codebase. It was an app that had been written years before by a consulting shop that was no longer "on good terms" with the client.

The company did an exceptional job commenting the code, but the programmers that maintained it since the original handoff were part of the "only change what absolutely needs to be changed" mindset which in itself is not bad. Unfortunately, they kept that same attitude toward comments as well, leading to a pretty large disconnect between the comments and the code over time.

Answer 10

Last 3 projects I worked on I spent several days on each removing outdated, misleading, and just plain useless comments from the codebase. Where possible and necessary I replace them with more appropriate comments, but more often than not it's just a question of deleting the comment and moving on.

I've done the same on pretty much every codebase I've ever taken over from others, usually after it being unmaintained for a while and the original owners long gone and/or unwilling or incapable of doing proper handover.

Answer 11

It could be the decline in the use of comments. How much of anyone's code qualifies? For one, someone actually has to include comments for them to be outdated. Second, the code that was commented has to be changed. Not sure a high-percentage of code qualifies.

You only have to rely on one bad comment to ruin a large piece of an application and waste a lot of your time.

Answer 12

In a organization which churns out a lot of code, it is difficult to keep the comments in sync. The best way to understand what is happening is by using softwares which draw the control flow diagram of the module which you are working on. That is the only way to keep get a feel of what the software does.

Answer 13

It’s all a matter of yours and your company’s mentality. First, you should have code reviews. Second, if you review code and it has changed in a way that changes its meaning, part of the code review is obviously to check if users of the code are still fine, and to check that all comments are still correct. And a change with invalid comments is not accepted.