What's the least useful comment you've ever seen?

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?

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

Solution 2

Unfilled javadoc boilerplate comments are particularly useless. They consume a lot of screen real estate without contributing anything useful. And the worst part is that where one such comment appears, hundreds of others are surely lurking behind.

/**
 * Method declaration
 *
 *
 * @param table
 * @param row
 *
 * @throws SQLException
 */
void addTransactionDelete(Table table, Object row[]) throws SQLException {

Solution 3

I've found myself writing this little gem before:

//@TODO: Rewrite this, it sucks. Seriously.

Usually it's a good sign that I've reached the end of my coding session for the night.

Solution 4

// remember to comment code

wtf? :D

Solution 5

Something like this:

// This method takes two integer values and adds them together via the built-in
// .NET functionality. It would be possible to code the arithmetic function
// by hand, but since .NET provides it, that would be a waste of time
private int Add(int i, int j) // i is the first value, j is the second value
{
    // add the numbers together using the .NET "+" operator
    int z = i + j;

    // return the value to the calling function
    // return z;

    // this code was updated to simplify the return statement, eliminating the need
    // for a separate variable.
    // this statement performs the add functionality using the + operator on the two
    // parameter values, and then returns the result to the calling function
    return i + j;
}

And so on.

View more solutions

Comments

[Ross]

Heh, this reminded me of thedailywtf.com/Articles/SUSBSTITUTE_CODE.aspx

[Steve Jessop]

As for what should have gone there: "this appears to work around my crappy understanding of .NET's threading implementation"

[Scott Nipp]

Maybe the comment was just magic: catb.org/jargon/html/magic-story.html

[Saurabh]

This is a useful comment. It tells me that my predecessor didn't understand threads and/or .NET synchronisation functions.

[Toon Krijthe]

No, it can be quite useful to temporary eliminate code.

[CindyH]

I worked as a contractor for an electronic voting provider to make the code meet standards. I never saw the above comment, but another rule was that there could be no magic numbers > 1. So there was a lot of "CONST INT INT_55 = 55", with INT_55 used as if it had meaning. That passed requirements.

[CindyH]

I do exactly that, purely for vanity. When someone sees my nasty code, I want them to know that at least I know that it isn't the way things should be.

[Jay Conrod]

In my experience, seeing a TODO somewhere is almost a guarantee that whatever it is will never be fixed.

[GalacticCowboy]

Translation? Google's Italian-English only gets about half of it. Is it something like "abandon all hope, ye who enter here"?

[Daniel Cassidy]

//do nothing can be useful, if it appears in an empty block that might be mistaken for unfinished code. Whether you should ever have an empty block in the first place is another question.

[user3001801]

I suspect I know exactly where this habit came from. I took a C++ class in college where the professor would give us a template application and asked us to implement certain sections. She requireed us to use that exact commenting format to assist her in grading our work. Could be a carryover...

[Abizern]

Dante - en.wikipedia.org/wiki/Divine_Comedy

[Mike Cole]

You lie. No way that is true.

[Steropes]

True. I'm sure there was a reason he used the comments, such as a note to tell where he was in the code. He never removed them after he was done, however, and the end result was that almost every line was commented. He also used indention to indicate if the code was tested or not. If you came across a large block of code that was not indented, it likely wasn't tested very well.

[SecretDeveloper]

Sorry if i didnt make it clear in the answer. He commented method A, albeit with the minimum of comments. He then created method B,C,D,E... and used the same comment from A on all of them... I have since left that job so i dont have to look at it anymore. I think he did it so he could say to managers "Look! i comment EVERYTHING."

[Nick Lewis]

I saw const THE_LETTER_S = 83; in some code where I work now...

[Konrad Rudolph]

Huh? That's actually a very useful comment. Better yet would be to specify an assert (e.g. assert(false, "Code should never be reached")) or throw an appropriate exception but the comment's certainly better than nothing.

[John]

Yeah, just change someFlag to isTrue or something like that.

[John]

Fermat's last comment, apparently.

[snicker]

No empty blocks. Means you did it wrong.

[user3001801]

// This comment should never have been written.

[causa prima]

I normally do it when nesting if's, it makes it more readable.

[canadiancreed]

Wonder if having to take the course over again would finally drive the point home.

[JB King]

@Loren, do you leave that in for months at a time though? I can see putting it in initially, but months later still having that in the codebase does seem like a broken window.

[BalusC]

I use // Do nothing. or // NOOP so now and then. Some IDE's gives warnings on empty blocks. And not without reason.

[Matthew]

Wonder if the teacher would have the power to make them take the course over.

[Konrad Rudolph]

@Matthew: I don’t think this would be very useful. The only think that helps here is to make the students program – a lot. Do big projects. Forget all the other stuff in CS, it’s simply not important. CS students don’t program, and that’s the problem. After they can program you can teach them advanced concepts. And don’t come to me with the claim that “CS isn’t programming” because that’s bullshit.

[BoltBait]

The programmer was being paid by the line?

[causa prima]

Why would I remove it? It makes it clear what's going on.

[causa prima]

Place marker. I've done similar things--but it shouldn't be left there!

[JB King]

To my mind, I'd find it to be a bit of an eye sore. I'd read the line and wonder, "If you aren't doing anything then why not just delete the line?" and then snip away the unnecessary code to make things a bit more compact. If there are millions of places in the codebase where there is a comment that says to do nothing, it just rattles me in a sense. Kind of like how people don't wear clothes that constantly play music yet. Some may find it cute and others would find it annoying quickly.

[Guge]

+1 I love your answer. The whole point of source code is that it should be readable to compilers AND people. This is the complete reason of existence of source code! The program doesn't do what the comment says, it does what the code says. If you can't read the code, it is either in need of refactoring, or you're in need of skill, or it is written in a less then good programming language.

[David Thornley]

If that was C++, good thing it wasn't //??/ (which translates to `//`, with the newline escaped). Repeated question marks frighten me, because they might be trigraphs.

[mpen]

that's what version control is for.

[mpen]

Is this C++? Should be made pure virtual.

[HXCaine]

This is what I imagine when I hear people say things like "We have written over 20,000 lines of code for this project"

[Can Poyrazoğlu]

according to conventions and comments used, it's C#