What is the worst comment you have ever read in code, and why, and what should have been written?

Question

I'm hoping that we can all educate each other from our experiences of being misled by comments, or just emotionally scarred by them :)

By the way, I know someone already asked what is the best comment you've ever written, but I think we're likely to get more helpful (or at least, different) content here.

---

this wasn't mentioned as already asked when I entered my question.

Answer 1

Ignoring comments of no worth, such as jokes and art, I think the top of this list should be...

Every comment that is factually incorrect. Documentation for a function or code block that is provably, or even obviously, wrong.

Answer 2

// Return FALSE
return true;

...because of its superfluousness, verbosity (in relation to the code it documents), and the fact that it still got it wrong.

Answer 3

// increment the counter
count++;

What should have been written? Nothing.

Answer 4

I've seen this too often ...

/*
* function name: foo
* out arguments: None
* in arguments: None
*/

int foo( bar arg1, bar arg2, bar arg3);

Answer 5

// return the result
return result;

because: it's superfluous

should have been:

return result;

Answer 6

In production VB6 code as supplied from the vendor. Halogen was a comm library supplied from the same vendor

'Wrap Around to stop Halogen Shitting itself

Answer 7

////////////////////////////////////////////////////////////////////////////////
// D**** P********'s silent soapbox:
//     I found the following in the header file, which is stuff you should not 
//     find in header files (variable definitions and non-inline function 
//     bodies.)  The only reason the program compiles this way is that it is 
//     written in just one source file, when it really, really, REALLY should be 
//     broken up.  Into, say, oh, 15 different modules.  This source file is 
//     so large, the most bloated MFC module is less than half the size.
////////////////////////////////////////////////////////////////////////////////

I thought it was very passive aggressive, especially for a co-op student. One shouldn't go adding comments like this to other peoples code.

Answer 8

i can asure you i am not lying these were comments a friend find while giving support to a system.

1.-
    //This function gathers all the data it needs to set in one loop, then sets it in a second. //Why?
         //This is so that the actual data change is all done as close to atomically as possible. 
        //Implementing locking on this data would be difficult and complicated, so instead of "fixing"  
        //the problem, we "minimize" it.

2.-
    // a hack to keep validator happy. it never validates but has sonmething to assign otherwise would get nasty error:ControlIdToEvaluate not assign



3.-     
        //The following code was cobbled together very quickly and is now held together by the
     //equivalent of peanut butter and prayer. Some of what it does seems stupid -- some of 
    //those things actually are stupid, but some are necessary.

the code is not available due to confidentiality agreements but they are true

Answer 9

This comment preceded a particularly hairy piece of code that the author obviously thought was too hard to understand by mere mortals.

/* Here be dragons */

Personally I would have preferred an ever-so-brief explanation of what the code was meant to do, rather than a warning.

Answer 10

I once saw

// ???

at a certain place and that truly made me wondered for a while.

Answer 11

Well, let me put it this way: I once worked on a legacy application which was intentionally written in an obfuscated fashion so the original author could continue to milk consulting fees when the software needed to be maintained. One time, I was curious so I grepped the code comments for the word:

nightmare

There were 22 matches.

Of course some of the class names were Banshee and Medusa. Did I mention it was a business application?

Answer 12

Leaving aside all the crappy comments one finds in code written by beginners, I think the worst comment of all time has to be the famous one in the Unix kernel:

You are not expected to understand this.

A close second is one of Lennart Augustsson's; unfortunately I can't find the original code, but it was something like

apply f = apply f    -- the ice is getting thin here

It looks like apply is just an infinite recursion, but the apply on the right is actually a compiler intrinsic, so it's OK. But as Lennart said, the ice is getting thin...

Answer 13

Comments that is written in foreign languages where most people in the project use and speaks English!

Answer 14

// THIS SHOULD NEVER HAPPEN

Seems popular on Google Code

Or

// not sure why this works!!

Answer 15

// To be fixed later

Why not just build more crappy code over the old ones...

Should be:

Fix it now and build the rest of the code over working ones.

Answer 16

I'm guilty of adding a header with a "last modified" date in it that I perpetually forget to update as I make changes to my code. I should probably just start naming it "date created".

Answer 17

I don't remember the exact wording but back in the times when I did some MFC stuff I once came over the following comment in one of the header files:

/* No longer supported. Never worked anyway. */

Answer 18

//TODO HÄ? WHAT YOU'RE DOING HERE?

Answer 19

// Fix it

Because you never know exactly what portion of the code is related to the comment, what's the history of this code and what the author had in mind when he wrote it.

Answer 20

 //The last minute express rolls again...

I find this from time to time in our legacy code. I guess that happens when you get set unrealistic deadlines.

Hmm, I have a compound fracture, where did I put that sticking plaster???

Answer 21

// Do Stuff

or

// You can't get here from there!

Answer 22

French comments to french code. No I don't speak french :)

Answer 23

bool some_fun( something )
{
    if( something )
    {
        return true;
    }
    else
    {
        //return false;
        return true;
    }
}

Not just a comment, but it's not funny if you don't see it in context.

Answer 24

We had a consultant working on some code that wrote

// Little bunny wants his carotts back.

He even spelt Carrots wrongly. The context did not involve bunnies or vegetables: it was some GUI code for a corporate application.

Answer 25

// Not sure why this works, wo I'm leaving it alone

or

// I don't know how this works, but it returns the right answer so who cares

Answer 26

There is a legend of a program, written in assembler, with the single comment

; happy birthday, Wolfgang

-because the instructions it was attached to, when converted down to the object binary code read 17560127, or some variation thereof. I never saw it, but the legend persists....

OTOH, I really did see the source code - again, written entirely in 8086 assembler for a BIOS (this was circa 1987), that had very few comments in there at all. I never thought that the listed owners actually wrote that though.

Answer 27

In an exception handler:

-- what should we do? log the error ^^? --

That is really bad... There has to be an exception handler with log functionality or a new exception.

Answer 28

Har! I found the following in code:

//fprintf(stderr, "Cannot open [%s] for reading\n", filename);
fprintf(stderr, "Cannot open [%s] for reading\n", filename);

I see a lot of these in the codebase I inherited last year:

//TODO: Don't crash here so often
//TODO: Needs critical section
//TODO: Implement this function

And all in real-live called code. Conceded I think I added the second one when I realised that it was needed, but there's a lot of todos in live code for new features that we obviously ran out of time to build.

Answer 29

# FIXME -- Use proper argument name
def get_flatten_list(foo):
    ...

Answer 30

In a Cocoa Touch app:

[sweet release]; // Ahh...