What's the least useful comment you've eve

Question

We all know that commenting our code is an important part of coding style for making our code understandable to the next person who comes along, or even ourselves in 6 months or so.

However, sometimes a comment just doesn't cut the mustard. I'm not talking about obvious jokes or vented frustraton, I'm talking about comments that appear to be making an attempt at explanation, but do it so poorly they might as well not be there. Comments that are too short, are too cryptic, or are just plain wrong.

As a cautonary tale, could you share something you've seen that was really just that bad, and if it's not obvious, show the code it was referring to and point out what's wrong with it? What should have gone in there instead?

See also:

• When NOT to comment your code
• How do you like your comments? (Best Practices)
• What is the best comment in source code you have ever encountered?

Answer 1

Just the typical Comp Sci 101 type comments:

$i = 0; //set i to 0

$i++; //use sneaky trick to add 1 to i!

if ($i==$j) { // I made sure to use == rather than = here to avoid a bug

That sort of thing.

Answer 2

GhostDoc comes up with some pretty interesting ones on its own.

/// <summary>
/// Toes the foo.
/// </summary>
/// <returns></returns>
public Foo ToFoo()

Answer 3

a very large database engine project in C many many years ago - thousands of lines of code with short and misspelled variable names, and no comments... until way deep in nested if-conditions several thousands of lines into the module the following comment appeared:

//if you get here then you really f**ked

by that time, i think we knew that already!

Answer 4

Default comments inserted by IDEs.

The last project I worked on which used WebSphere Application Developer had plenty of maintenance developers and contractors who didn't seem to be bothered by the hundreds, if not thousands of Java classes which contained the likes of this:

/**
 * @author SomeUserWhoShouldKnowBetter
 *
 * To change this generated comment edit the template variable "typecomment":
 * Window>Preferences>Java>Templates.
 * To enable and disable the creation of type comments go to
 * Window>Preferences>Java>Code Generation.
 */

There was always that split-second between thinking you'd actually found a well-commented source file and realising that, yup, it's another default comment, which forced you to use SWEAR_WORD_OF_CHOICE.

Answer 5

I once worked on a project with a strange C compiler. It gave an error on a valid piece of code unless a comment was inserted between two statements. So I changed the comment to:

// Do not remove this comment else compilation will fail.

And it worked great.

Answer 6

In a huge VB5 application

dim J
J = 0 'magic
J = J 'more magic
for J=1 to 100
...do stuff...

The reference is obviously THIS ... and yes, the application without those two lines fails at runtime with an unknown error code. We still don't know why.