does an incorrect comment smell?

Question

I just had a situation where I was reading some code while working on a bug and I noticed an incorrect comment (the code did not do what the comment said it did). I just thought "hmm, ok" and went on working on the bug. About an hour later I was back at that line of code, having determined that it had caused the bug. In fact, if the code had really done what the comment said it did, then the bug would not have occurred.

I'm wondering if that was just a coincidence or if I should have focussed on that inconsistency right away.

Answer 1

Although comments can sometimes be added too much, if used properly, they document the intentions of the developer and the code. Therefore, any discrepancy between what a comment says and what the code does should indicate an issue, even if it is just that the comment is incorrect.

Whether or not you should concentrate on this when looking for a bug is rather subjective as it really depends. After all, how can you really know that the code is wrong and the comment is right or vice versa until you've actually looked into it?

When it comes down to it, if the comment does not match what the code does, then there is definitely a smell. How to actually fix it is where your skill comes in.

Answer 2

Comments lie!

Answer 3

In general, people almost always get the comment correct, and the code incorrect.

That's just a fact of life, people say they want one thing but end up producing something else. Whether or not that was intentional is hard to say. Here's what I do know, if the method or function is not performing the task as described in the comment, then I would make it perform that task unless I knew myself what the function/method is supposed to do.

Most bugs are due to a discrepancy between what the developer intended and what they did. Comments are usually written down as the intended functionality of the code, and not the actual functionality.

Answer 4

Sometimes commented code is worse than uncommented code. This will probably get me some negative votes but consider how much time you wasted chasing that inconsistency down. Comments that don't seem to match the code always raise red flags for me. Sometimes the comments are for commented-out code!

Answer 5

Bad and misleading comments are much worse than no comments so I would delete the comment or update it.

Answer 6

Comments are a great way for developers to verbalize the functionality they're trying to create. I've caught myself in a number of logical inconsistencies while trying to devise comments for trickier pieces of code.

I would suggest focusing on inconsistencies in comments. They may very well point to bugs. At the very least, the comments should be consistent with the code. Ideally, they should be illuminating and insightful.

Answer 7

The comment is a lie.

Answer 8

This inconsistencies happen all the time and yes, you should update it right away.

Comments are usually not updated as fast as the code, because mmm it's a comment, so always keep comments updated and tell your coworkers about it.

Answer 9

Comments and code should definitely match. If you encounter an inconsistency, you should investigate and fix whichever piece needs fixing....or at the very least, annotate the discrepancy to help someone else deal with it later.

Answer 10

If code and comments do not match, that is simply a bug that should be fixed, just like any other bug.

You'll still need to figure out whether the bug is in the code or in the comment, though...

Answer 11

A comment that doesn't match the code just indicates that someone forgot to update the comment when they updated the function. In and of itself, that's not a smell. However, if they forgot to change the comment because the function is so long that they forgot it, then it's a smell. But that would be a smell with or without the comment.

Bear in mind that a smell is something that indicates that there's something else wrong. Thus an incorrect comment isn't really a smell. It's just bad code.

Answer 12

If I accepted the idea that code can "smell", I would definitely say yes. An incorrect comment is worse than no comment. It actively misleads the developer.

But since code can't "smell", no, incorrect comments do not smell. They are simply dangerous bugs that should be fixed immediately.

Answer 13

Old, incorrect comments smell.

In an area under active development, it's quite likely that comments will go out of date. But prior to finishing up, comments should be brought up to date.

Answer 14

Incorrect comments are the worst kind of comments - they aren't just worse then having no comments at all, they're worse then uncommented code using one letter variables. Programmers rely on logic and rules to solve problems - we use our "facts" to eliminate the impossible, until what remains, however improbable, is the root cause. Introducing false information breaks the entire debugging process.

Incorrect comments are definitely code smell - the most common place I see them is an effect of maintenance. Someone modified the code without modifying or checking that the comments where still correct (or worse, it's one of those organizations that use the "comment out the old code"© version control system). Occasionally the code never worked in the first place, but was never actually tested.

What you are smelling is poor change control and testing practices.

Personally I like to keep commenting to only the comments that matter (broad descriptions, explainations of complex segments, parameter in/out rules, and known limitations and hacks) for precisely this reason - every redundent comment you write is like an entra line of code that must be checked and "tested" during maintenance.

Answer 15

False comments reek to high heaven. I would recommend using svn blame - or the equivalent in your version control system - to find out when the comment and the code got out of synch. If they were always out of synch, more work is needed. But if they used to agree, and the code changed at some point, you can see why it changed and - one hopes - update the comment to match. If the comment changed, again: try to understand why; maybe the code needs to be updated to behave in accordance with the comment. If - as in your case - the discrepancy exposes a bug, figure out why (presumably) the code changed, and see whether reverting the code to match the comment will break something else (it's likely, otherwise why was the code changed). Work out test cases that ensure correct behavior for both situations (the one that worked before the code change, and the one that caused the code change), tease apart the functionality into (maybe) separate methods, and check everywhere the function is called to see which function should be called. Make the changes, run your tests - and update the comments to make them match the code, and best of all to explain why the code is doing what it is.

Answer 16

I'm wondering if that was just a coincidence or if I should have focussed on that inconsistency right away

It really depends. If the block of code makes your eyes glaze, it's understandable.

However, I think one should be immediately suspicious of comments that are TOO specific. In contrast, comments that outline blocks of code and leave out as many details as possible have staying power.

Answer 17

I have worked with code for a long time now and I have never ever trusted what the comment stated. If I were to fix a bug I would debug the code, test the outcome against what is required (bug, change, enhancement etc.). Then once I am all is well then I would update or leave the comment as is.

Code comments don't compile. Code does...

Answer 18

Yes. This is a smell

Remove the comment and fix, refactor the code adding a comment when you check it in