Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

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?

share|improve this question
28  
Agreed. Outdated code made into a comment, now that's something I see a lot - and would like to see less of. –  pyvi Apr 19 '11 at 13:53
8  
I see more lack of comments whatsoever than anything. Combined with poor naming conventions its a ball of fun trying to read some of the stuff I work with. –  P.Brian.Mackey Apr 19 '11 at 13:59
2  
I've seen a lot of outdated comments, some were just plain misleading EVIL. Definitely no myth, but is mostly valid for projects that are maintained by many people and/or for a long time, amplified by complexity. However I learned to trust the code, not the comments (I almost never read them if they exceed more than one two lines). –  MaR Apr 19 '11 at 18:10
    
I've been mostly working with a very old legacy code throughout my whole career. There've been about a dozen of times when I had some severe problems related to outdated comments in a weird 30 years old Fortan77 code, but it was a close to zero percentage of the code where comments were adequate. So I agree, the scale of a problem must have been exaggerated. –  SK-logic Apr 20 '11 at 10:05
    
Just my luck, I've seen quite a few in the year since I posted this. I guess I had subconsciously learned to not trust them, then to correct them and move on, without giving it enough thought to put into my long-term memory. –  Karl Bielefeldt Aug 14 '12 at 4:58

12 Answers 12

up vote 31 down vote accepted

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.

share|improve this answer
    
So basically you are saying you simply ignore comments altogether because it's too big of a mess already, only making your situation worse. Hardly surprising. –  Steven Jeuris Apr 19 '11 at 16:21
5  
@Steven - Me personally, no. I'm a big believer in incremental improvement. I've seen snarls of completely indecipherable code turned into something quite decent with enough gradual effort. But, ignoring is certainly the norm in my experience. It's very understandable when you encounter several intertwined 10000 line classes with weeks worth of problems to catalog, that outdated comments tend to fall towards the bottom of the priority list. –  Steve Jackson Apr 19 '11 at 16:34
1  
@Steve: In your situation I would simply create a script which removes all comments then, and start commenting from scratch where needed. :) –  Steven Jeuris Apr 19 '11 at 16:40
1  
main code base where I used to work was at least half comments and rarely commented code. Outdated comments were a fact of life, correct comments were exceedingly rare and I will not even begin to comment on the documentation !!! sight... After this job I learned that less is good, if you code needs comment, it probably needs a refactor to make things more obvious... –  Newtopian Apr 20 '11 at 2:49
4  
I've seen some awful examples of Blocks of copy-pasted code including comments. Comment may have made sense in its original location, but hardly makes sense here. Class-levels comments talking about a different class, for example. –  Peter Taylor Apr 20 '11 at 8:38

"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.

share|improve this answer
    
As I've become better, I've found I need less comments to grasp what code does in typical plug n chug code. –  Paul Nathan Apr 20 '11 at 5:36
3  
@Paul Nathan, comments should never describe what the code does - the code describes that better. Comments are there to explain, why the code does what it does. –  SK-logic Apr 20 '11 at 10:08
2  
@SK-logic: Although I understand the argument I believe it's too broad. The comments of a function (or code paragraph/block) can clarify a lot more (and quicker) what the function does than its name. This is especially needed for public functions. As easy as code can be to read, reading a two-liner explanation of 10-liner code is still faster. Imagine working with your favorite API which doesn't have any "what" documentation. You'd be a lot less sure about its functionality. –  Steven Jeuris Apr 20 '11 at 10:22
    
yep, I did not include a documentation (e.g., Javadoc) - it is too structured to be called just "comments". –  SK-logic Apr 20 '11 at 10:43

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.

share|improve this answer
    
"Outdated comments are a job smell." Very well put! Likewise self-documenting code only without any comments isn't the solution, but a lazy 'hack'. –  Steven Jeuris Apr 20 '11 at 9:58

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.

share|improve this answer
    
Can I ask what industries you've worked in? I'm wondering if this is more common in some than others. –  Karl Bielefeldt Apr 19 '11 at 14:46
    
I have worked in 3 different countries in Europe, mostly as a consultant for a big company and a small one. Lately in a SaaS development house. –  Kim.Net May 17 '11 at 9:34

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.

share|improve this answer
3  
(Not a criticism - just presenting a solution) IDE warnings can go a long way toward preventing this. If more drastic measures are needed, fail the build on a javadoc build warning/error. –  Michael K Apr 19 '11 at 14:22
1  
This could explain why I haven't seen very many. I haven't ever worked somewhere that uses JavaDoc-style comments. –  Karl Bielefeldt Apr 19 '11 at 14:44
4  
@Michael, IDE warnings are helpful in mild cases. Our legacy codebase produces over 20,000 Checkstyle warnings, that's way over the limit where you stop paying attention :-((( IDEs, when used badly, can contribute to Javadoc misery significantly. Most of the crap Javadoc in our codebase was obviously autogenerated. –  Péter Török Apr 19 '11 at 15:05

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.

share|improve this answer

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.

share|improve this answer

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.
share|improve this answer
1  
The problem in this case is probably the misuse of TODOs. I believe TODOs should be only used when the code is actually functional but improvements could be made later, so TODO: implement kind of comments should not exist and the fact that no one actually came back doesn't matter that much. Sadly, not a lot of people adhere to this rule and I totally agree I'd like to see a comment like you posted in some production code at some point. It'd make my day. –  pwny Apr 19 '11 at 16:08
1  
In C# I use the NotImplementedException for those purposes. –  Steven Jeuris Apr 19 '11 at 16:27
1  
@pwny, I only use TODOs on things I plan to write before I check in, to make sure I cover it. Anything longer term than that belongs in a bug tracker instead, in my opinion. –  Karl Bielefeldt Apr 19 '11 at 18:08
    
@Karl Bielefeldt That makes a lot of sense as well. –  pwny Apr 19 '11 at 18:29

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.

share|improve this answer

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.

share|improve this answer

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.

share|improve this answer

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.

share|improve this answer

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.