views:

5441

answers:

101

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:

+105  A: 

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.

Rich Bradshaw
Damn that's sneaky =)
Ross
Going to have to do some major refactoring if $x = $y is now a bug...
iAn
I like the sneaky. Heh.. :)
Till
Nothing like a sneaky add 1!
Rich Bradshaw
this is so true...go dig up one of your first programming assignments.
dotjoe
that made me lol
Mike C.
I think these sort of comments occur because professors tell their students that they get points off if they don't comment their code, but never spend the time to explain to them the proper use of a comment.
Ryan Smith
I actually had profs require a comment on EVERY LINE, so instead of commenting the obvious stuff like i++; I would put jokes about what the code was doing instead. I think they appreciated it.
Neil N
Oh god how I hated that "comment your code in assignments" policy!
HeavyWave
I also had profs that required a comment every line. Admittedly this was when names were generally pretty short.
Loren Pechtel
I think at this stage it plays a big part in learning programming as a beginner. when you go back you'll remember not to use = for comparison. fair enough after a couple weeks it will be plain obvious, but before that it really helps :)
Zeus
Yeah, I agree - when starting out it's invaluable, especially if you are working in a group on code where you all don't have a clue!
Rich Bradshaw
+49  A: 

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.

Ross
Sometimes, it really sucks.
Gamecat
But that's the MOST useful comment you will see!
Martin Beckett
But it isn't useful, because you can see whether the code sucks without reading the comment!
finnw
that is very useful, just search for all the TODO items and you have a task list for the next week...or month...or year ;-)
Steven A. Lowe
The funny thing is, is that comments like that are left around, even after the code is fixed up, so that it doesn't suck.
Kibbee
In my experience, seeing a TODO somewhere is almost a guarantee that whatever it is will never be fixed.
Jay Conrod
@JayConrod - Just like any other TODO-list..
sshow
Our Continuous Integration system (Hudson) picks these up and give minus points using Continous Integration Game to commiters - HACK and BUG lowers one's score by -25, TODO is -10 and NOTE is -5.
Esko
Even worse when you do the task but leave the TODO.
Matthew
+31  A: 

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.

Gamecat
Heh, this reminded me of http://thedailywtf.com/Articles/SUSBSTITUTE_CODE.aspx
Ross
@Ross, Great i like his style.
Gamecat
I had that too once, I think it was an uninitialized pointer and the comment would have an effect on the memory layout.
Morten Christiansen
Maybe the comment was just magic: http://www.catb.org/jargon/html/magic-story.html
skymt
That sort of weirdness happens, but it is probably worth documenting which compiler version and which platform - at least, if your code is used across different platforms. The compiler version is worth documenting, because in five years, it is unlikely that the compiler will still have the trouble.
Jonathan Leffler
Its 10 years and five companies ago. IBM visual age c compiler if i remember correctly. Could also have been mainframe code.
Gamecat
Stuff like that used to happen with Visual Basic 6.0. More than once it happened that application crashed for no particular reason. Switching two non-related pieces of code usually solved it.
Josef Sábl
i can remember something of this sort happening as well, but it was with GCC, and as I remember the bug was fixed the next release. Good old open source.
MatthieuF
This is why you should always leave the switch set to "More Magic".
camccann
+36  A: 

Every comment that just repeats what the code says is useless. Comments should not tell me what the code does. If I don't know the programming language well enough, to understand what's going on by just reading the code, I should not be reading that code at all. Comments like

// Increase i by one
i++;

are completely useless. I see that i is increased by one, that is what the code says, I don't need a comment for that! Comments should be used to explain why something is done (in case it is far from being obvious) or why something is done that way and not any other way (so I can understand certain design decisions another programmer made that are by far not obvious at once). Further comments are useful to explain tricky code, where it is absolutely not possible to determine what's going on by having a quick look at the code (e.g. there are tricky algorithms to count the number of bits set in a number; if you don't know what this code does, you have no chance of guessing what goes on there).

Mecki
Exactly, code should be self-documenting - comments are just reasoning/evidence for writing that code
Ross
One wise man wrote that, when comments can directly disagree with the source code, they're wrong.
David Thornley
Heck, how about: i--; // Increase i by one
David Thornley
They aren't completely useless - they inform you the code was either written by a fresh grad, or an idiot. A very useful piece of data if you are struggling with the "is this code wrong or is it me?" question.
Martin Beckett
+18  A: 
// Don't know why we have to do this
kronoz
But I've done that!
MatthieuF
Well don't do that!
jskulski
I need to wait five seconds in between upvoting both of those comments. Ok I thinks its been five seconds.
SP
@SP: You jerk, made me wait an *extra* 5 seconds.
Mark
A: 

I thought this was about the worst comment on a SO post, and was disappointed to find otherwise.

MidnightGun
+2  A: 

Not quite a comment, but from the JavaDoc that described the API of a system I once had to work with.

setAttribute(attributeName, attributeValue)
Sets an attribute

Nowhere was it documented what an attribute was (they were not HTML/XML/etc attributes), what attributes existed or what values they could have.

David Dorward
A: 

Commented code is the least useful comment :)

goths
No, it can be quite useful to temporary eliminate code.
Gamecat
+1  A: 

I have removed the name to avoid embarassment but this is a comment found in some production code. Unfortunately, as this was ASP code, referring to a VB6 module, and the customer was quite inquisitive, it was she who pointed out the comment to me whilst I was on-site during a consultancy visit. Luckily she had a sense of humour about it.

'I don't know how the help this @"%& works. It is a load of &£$! created by that contractor ---------.
I will just leave it in place and hope nobody ever needs it changing.

Unfortunately for me the code did need changing about a year later, at which point we found we had no source code and had to junk it and rewrite for free.

BlackWasp
+34  A: 
Thread.Sleep(1000); // this will fix .NET's crappy threading implementation
MusiGenesis
As for what should have gone there: "this appears to work around my crappy understanding of .NET's threading implementation"
Steve Jessop
This is a useful comment. It tells me that my predecessor didn't understand threads and/or .NET synchronisation functions.
finnw
Hey, that's not real, is it?!
Chris Farmer
Seen much real-world code, Chris? :)
MusiGenesis
+8  A: 

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.

Axeman
Try cutting a wire ;-).
Gamecat
WTF?! It's magic...
Nelson Reis
I've had to do strange things like that in an old VB6 project...
Echo
+72  A: 

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 {
Diomidis Spinellis
I agree. Lots of people think that this is "documentation". I've had some arguments with people who thought that is all they had to add.
Till
Yep... I hate these things! They'd be nice if people actually filled them out though.
TM
You know... there are organizations that measure code quality by the amount of JavaDocs. No, really!
Yaba
Even worse is making the mistake of trying to use the documentation produced. There are so many 'manuals' that are nothing more than a list of classes, methods and parameter names. At least when you're looking at the source you can fall back on reading the code to figure out what's going on.
Michael Burr
All that does is:a) Trick automatic code style checkers into thinking you doc'd your method so that you don't actually have to do so to pass.b) Trick whatever automatic code style checkers into thinking you doc'd your method so that nobody notices it isn't doc'd until they need the documentation.
Adam Jaskiewicz
I like javadoc in principle, because if you do it right you've got a quick overview, and I do it more or less right. Unfilled, on the other hand, are as useful as a C++ .h file, and less succinct.
David Thornley
+1 Absolutely. Absolutely
MatthieuF
Unfilled Javadoc comments are the second worst. The only thing that's worse are *filled* Javadoc comments -- they usually contain the same amount of useful information (none), and waste even more space.
Jerry Coffin
@Jerry Coffin: amen to that. When filled out, they usually tells you wonders such as that the `table` parameter is "the table", and sometimes, if you're lucky, that it has type `Table`. Tbh, I'd rather see the comments in the accepted answer (stuff like `//set i to 0`, because at least those are usually written on the same line as the code, so they take up less screen space.
jalf
+4  A: 

Just the typical Comp Sci 101 type comments:

I have threatened my students with random acts of extreme violence if they ever did this in assignments. And they still did. The sense in proper indentation, however, seemed to be totally lost to them. Goes to show why Python would be the ideal language for beginners, I guess.

Konrad Rudolph
Wonder if having to take the course over again would finally drive the point home.
canadiancreed
Wonder if the teacher would have the power to make them take the course over.
Matthew
@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.
Konrad Rudolph
+13  A: 

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.

insin
Even worse is default comments inserted manually! I've seen that, too.
camccann
+4  A: 

Comments generated by an auto-javadoc tool (e.g. JAutoDoc). I had a team member submit a large amount of code that was commented like:

/**
 * Gets the something
 *
 * @param num The num
 * @param offset The offset
 */
public void getSomething(int num, bool offset)

Maybe it's helpful as a starting point, but by definition if the program is parsing the variable and method names to make its comments it can't be doing much useful.

sk
+6  A: 

100k LOC application that was ported from vb6 to vb.net. It looks as though a previous developer had put a comment header on one method and then copied and pasted the exact comment onto every method he wrote from then on. Hundreds of methods and each one incorrectly commented...

When i first saw it i laughed... 6 months later the joke is wearing thin.

Kaius
That's what you get for trying to use coding standards to force developers to add comments in the hope they'll be useful.
finnw
Care to tell what that comment said?
DR
I'm curious about the content of that comment...
Nelson Reis
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."
Kaius
+23  A: 

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

/// <summary>
/// Toes the foo.
/// </summary>
/// <returns></returns>
public Foo ToFoo()
Mark
I don't like GhostDoc. All it does is allow developers to check the box that "methods must have header comments" without the comment adding any value. Even when GhostDoc gets it right, it restates the obvious.
Anthony
@Anthony: Any tool that can give you a short-cut is abused if you don't follow-up by giving meaning to what it gave you. So regardless of the tool, the quality of the comments only reflects the programmer's ability. The only way to fix this is by code-review, which I know many companies can't afford...
scraimer
@scraimer The problem with GhostDoc is that it cannot infer anything that I wouldn't infer by reading the method signature. If you have check-in policies in place to prevent undocumented members, GhostDoc allows for that policy to be technically satisfied, but in so doing, subverts its spirit.
Mark
GhostDoc is a good tool when used properly. The proper use of GhostDoc is to ensure that doc comments comply with standard conventions for writing documentation.
Pavel Minaev
Try AtomineerUtils (google it).For the above, it generates://<summary> Converts this object to a foo. </summary>//<returns> This object as a Foo. </returns>As you say, this doesn't tell you any more about the function than you could infer, but in most cases it's less work to modify this to write a good comment than it is to write the whole comment from scratch. And it word wraps the comments to keep them tidy, too.
Jason Williams
But it doesn't toe the foo. It foos the bar.
tsilb
+12  A: 

My favorite all-time comment.

/* our second do loop */
do {

Whoever wrote it - you know who you are.

They really are rare!
SapphireSun
+2  A: 
/* FIXME: documentation for the bellow functionality - and why are we doing it this way */

It was a huge statistical program for an accounting application. We had never figured out why she had done it that - wrong - way. But we had to rewrite it, and paid penalty for the customer.

Zsolt Botykai
+17  A: 

Came across a file once. Thousands of lines of code, most of it quite horrendous. Badly named variables, tricky conditionals on loops and one comment buried in the middle of the file.


   /* Hmmm. A bit tricky. */
Andrew Edgecombe
+4  A: 

Whenever I teach OOP in C++ or Java, I typically get the following:

// My class!
Class myclass 
{
    //Default constructor
    public myClass()
    {
       ...
    }
}

My policy is to announce to students that they would lose points for both insufficient and superfluous documentation

Uri
If they leave out that comment how will you tell their classes from other people's?
JohnFx
+3  A: 

My research deals with API usability and I've encountered a lot of comments which are bad simply because they are misleading, misplaced, incorrect, or incomplete.

For example, in Java Messaging Service (JMS or within J2EE), the QueueReceiver.receive class contains the following gem: "This call blocks until a message arrives, the timeout expires, or this message consumer is closed. A timeout of zero never expires and the call blocks indefinitely."

Sounds great? right?

Problem is, as my lab studies show, that users believe that comments cover everything. Faced with a situation where messages are not received, they refuse to look elsewhere for the explanation.

In this case, when you create a QueueConnection from the QueueConnectionFactory, it tells you that the messages would not be delivered until start is called. But that does not appear in the receive method.

I believe that if that line wasn't there, more people would have searched for it elsewhere.

By the way, my study deals with JavaDoc usability in general, and in whether people actually find the important directives in JavaDocs. If anybody wants to take a look, a related is here.

Uri
+26  A: 

I don't believe it. I came into this question after it had 22 answers, and no one pointed out the least possibly useful type of comment:

comments that are wrong.

It's bad enough that people write superfluous comments that get in the way of understanding code, but when someone writes a detailed comment explaining how something works, and it's either wrong in the first place, or wrong after the code was changed without changing the comment (much more likely scenario), that is definitely the worst kind of comment.

David M. Karr
Maybe you should've provided such a comment yourself. Since your didn't, your answer is even less helpful than the 22 answers you are complaining about.
vog
+5  A: 

I have a lot of these:

# For each pose in the document
doc.elements.each('//pose') do |pose| ...

# For each sprite in sprites
@sprites.each do |sprite| ...

# For each X in Y
for X in Y do ...

I'm trying to cut back on that, though. :(

Firas Assaad
is there a +1 funny?
Christopher Mahan
no i don't think so!
Mitch Wheat
I tend to do this while planning the algorithm. I should really clean up once I'm done though...
Drew
+7  A: 

The worst comment is one that gives a wrong explanation of what the code does. That is worse than no comment at all.

I've seen this kind of thing in code with way too many comments (that shouldn't be there because the code is clear enough on its own), and it happens mostly when the code is updated (refactored, modified, etc.) but the comments aren't updated along with it.

A good rule of thumb is: only write comments to explain why code is doing something, not what it does.

Tom De Leu
+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.
Guge
+1  A: 

I would have to say that the least useful type of commenting I have encountered is second-language commenting.

I would rather see the comments written clearly in someone's native language than scrawled in a very poor approximation of English. At least then a native speaker of that language could translate it. ESL comments are often unreadable to everyone on the planet except the person who wrote them, and sometimes not even by them.

+45  A: 
// remember to comment code

wtf? :D

Decio Lira
I often use this, but to write it shorter I just write "DOCME" (which I declare as a todo task... have really many tasks in my projects :p)
Vinze
Remember Sammy Jankis.
Nefzen
+19  A: 
// secret sauce
nilihm
+8  A: 

Taken from one of my blog posts:

In the process of cleaning up some of the source code for one of the projects I manage, I came across the following comments:

/*
   MAB 08-05-2004: Who wrote this routine? When did they do it? Who should 
   I call if I have questions about it? It's worth it to have a good header
   here. It should helps to set context, it should identify the author 
   (hero or culprit!), including contact information, so that anyone who has
   questions can call or email. It's useful to have the date noted, and a 
   brief statement of intention. On the other hand, this isn't meant to be 
   busy work; it's meant to make maintenance easier--so don't go overboard.

   One other good reason to put your name on it: take credit! This is your
   craft
*/

and then a little further down:

#include "xxxMsg.h" // xxx messages
/*
   MAB 08-05-2004: With respect to the comment above, I gathered that
   from the filename. I think I need either more or less here. For one
   thing, xxxMsg.h is automatically generated from the .mc file. That might
   be interesting information. Another thing is that xxxMsg.h should NOT be
   added to source control, because it's auto-generated. Alternatively, 
   don't bother with a comment at all.
*/

and then yet again:

/*
   MAB 08-05-2004: Defining a keyword?? This seems problemmatic [sic],
   in principle if not in practice. Is this a common idiom? 
*/
Scott Dorman
In-comment correspondence, just amazing O_O
Paggas
+8  A: 

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!

Steven A. Lowe
+36  A: 

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.

Robert S.
I love how the original developer was caring about "best implementation", yet does the calculation twice...
Michael Stum
Exactly the same way of commenting was shown to us at software engineering classes (sic!). Much-much overkill.
I can't decide if it's better or worse that the comments here fully document the parameters, purpose, and return value, but without ever using the XML comments that IntelliSense understands.
camccann
+3  A: 

I have a very bad habit of doing this, especially when I'm on a roll:

// TODO: Documentation.
bouvard
+2  A: 

A very large source file, implementing multi-threading in a single process. In the midst of all the call-stack switching and semaphore grabbing and thread suspension and resumption was a simple comment regarding a particularly obscure bit of pointer manipulation:

/* Trickiness */

Gee, thanks for sharing.

CJP
+7  A: 

Would definitely have to be comments that stand in place of error handling.

if(some_condition){
    do_stuff();
}
else{
    //An error occurred!
}
Jason Baker
+14  A: 
//' OOOO oooo that smell!! Can't you smell that smell!??!??!!!!11!??/!!!!!1!!!!!!1

If Not Me.CurrentMenuItem.Parent Is Nothing Then
    For Each childMenuItem As MenuItem In aMenuItem.Children
  do something
 Next

    If Not Me.CurrentMenuItem.Parent.Parent Is Nothing Then
        //'item is at least a grand child
        For Each childMenuItem As MenuItem In aMenuItem.Children
            For Each grandchildMenuItem As MenuItem In childMenuItem.Children
       do something
            Next
        Next

        If Not Me.CurrentMenuItem.Parent.Parent.Parent Is Nothing Then
            //'item is at least a grand grand child
            For Each childMenuItem As MenuItem In aMenuItem.Children
                For Each grandchildMenuItem As MenuItem In childMenuItem.Children
                    For Each grandgrandchildMenuItem As MenuItem In grandchildMenuItem.Children
            do something
                    Next
                Next
            Next

        End If
    End If
End If
levi rosol
Corollary to the old "understanding recursion" adage: How can you understand recursion if you don't understand recursion?
Jeremy Frey
+1 for making me LOL
John at CashCommons
grandgranchildren?
johnc
+1 for the Lynyrd Skynyrd reference
Graeme Perrow
+15  A: 
try
{
...some code...
}
catch
{
// Just don't crash, it wasn't that important anyway.
}

*sigh

BoltBait
I've written code like that before! Sometimes it really isn't important :)
Dave
At my first job, it was a company policy, to write code like that. Of course every error was logged into file too. Once it happened that server was stuck in the loop, writing gigabytes of error messages to the hard drive.
Josef Sábl
@Dave -- I'm sure that what you thought it would catch isn't important, but what else might be thrown? Even if you want to discard an OptionalWidgetNotFoundException you might still want to let ComputerIsOnFireException escape.
camccann
If there's nothing you can do about it such behavior is common and not unreasonable.
Loren Pechtel
+1  A: 

Taken from legacy code, this was the only description of the following if condition's purpose (the condition spanned 4 rows at 120 cols):

#-- Whoa, now that's a big if condition.
Adam Bellaire
+7  A: 

This is an absolutely real example from a database trigger:

/******************************************************************************
   NAME:       (repeat the trigger name)
   PURPOSE:    To perform work as each row is inserted or updated.
   REVISIONS:
   Ver        Date        Author           Description
   ---------  ----------  ---------------  ------------------------------------
   1.0        27.6.2000             1. Created this trigger.
   PARAMETERS:
   INPUT:
   OUTPUT:
   RETURNED VALUE:
   CALLED BY:
   CALLS:
   EXAMPLE USE:
   ASSUMPTIONS:
   LIMITATIONS:
   ALGORITHM:
   NOTES:
******************************************************************************/
JosephStyons
Gosh this is sick... reminds me of the time we used comments like this instead of a decente data dictionary
rshimoda
Oh yes. Been there. Seen that.
MatthieuF
+1  A: 
// Magic
menu.Visible = False
menu.Visible = True

This is from the UI framework in some PowerBuilder code I used to work on. The framework created menu items dynamically (from database data). However, when PowerBuilder was upgraded from 16-bit to 32-bit, the menu code stopped working. The lead developer somehow determined that hiding the menu and then showing it caused it to display properly.

Paul Lefebvre
+5  A: 
/** function header comments required to pass checkstyle */
Bill the Lizard
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 saw const THE_LETTER_S = 83; in some code where I work now...
Nick Lewis
+1 cuz if I had to pass a checkstyle I'd be doing it too.
tsilb
+3  A: 

Extraneous comment breaks. Normally, if there's a logical separation of flow, a line of comments like:

/***************************************************************************/

above and below that section of code can be helpful. Its also nice for when you need to come back later and split apart a large function (that started out small) into several smaller functions to keep the code easy to read.

A former programmer, who shall remain nameless, decided to add the following two lines:

//-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
//-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=

After every single line of code.

Steropes
You lie. No way that is true.
Mike C.
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.
Steropes
The programmer was being paid by the line?
BoltBait
+2  A: 

Once I saw the following comment in some code:

//I know that this is very ugly, but I am tired and in a hurry. 
//You would do the same if you were me...
//...
//[A piece of nasty code here]
Doron Yaacoby
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.
CindyH
A: 
/* this is a hack.
 ToDo: change this code */
dotnetcoder
A: 

Quoting this from memory so it might not be exact.

I don't know what the f*ck this does, but it seems to work so I am not touching it.

The funny thing is the way I found out about it. This comment was embedded in an access application some developer in our company had written for a client and distributed in an MDB. Unfortunately the code that "seems to work" bombed and Access dutifully opened the code window with the debugger highlighting the line right below the comment. It didn't exactly inspire confidence with that customer.

JohnFx
+2  A: 

Here are my two favorites:

                // do nothing

This doesn't really help as it just takes up space.

Then somewhere further along:

        // TODO: DAN to fix this.  Not Wes.  No sir.  Not Wes.

I guess if I'm not Dan or Wes, I should just ignore this, right?

JB King
//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.
Daniel Cassidy
No empty blocks. Means you did it wrong.
snicker
I normally do it when nesting if's, it makes it more readable.
Loren Pechtel
@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.
JB King
I use `// Do nothing.` or `// NOOP` so now and then. Some IDE's gives warnings on empty blocks. And not without reason.
BalusC
Why would I remove it? It makes it clear what's going on.
Loren Pechtel
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.
JB King
A: 
//I am not sure why this works but it fixes the problem.

This one tops the list for my useless comments.

StubbornMule
A: 
// this is messed up, and no one actually knows how it works anymore...
madlep
+1  A: 

Once upon a time, I saw:

#region This is ugly but a mas has to do what a man has to do
Initialization of a gigantic array (...)
#endregion 
// Aren't you glad this has ended?

I was glad I was not that developer.

rshimoda
+4  A: 

The two most unhelpful comments I've ever seen...

try
{
  ...
}
catch
{
  // TODO: something catchy
}

I posted this one at the Daily WTF also, so I'll trim it to just the comment...

  // TODO: The following if block should be reduced to one return statememt:
  // return Regex.IsMatch(strTest, NAME_CHARS);
  if (!Regex.IsMatch(strTest, NAME_CHARS))
    return false;
  else
    return true;
GalacticCowboy
That's Brillant!
Gavin Miller
Understandable: Changing the code now is unacceptable either because it would require testing or because permission is needed.
Loren Pechtel
A: 

someone send me a c file which described a binary file his program created.

it contained no comments except somewhere in the writing of the real data

SwapArray(..); // Big endian ???
write();

I asked about the implementation of the SwapArray and he told me I didn't need it, it's just to make sure it works on linux machines.

After experimenting I found out that he used little endian every where (which is like normal) but only the real data was written in big endian. Normally you could see it in a hex editor, but the data was stored in floating point, so it's not that easy to notice the mixed endian.

Davy Landman
+3  A: 
cntrVal = ""+ toInteger(cntrVal)      //<---MAYBE THIS IS THE WAY I'M GOING THROUGH CHANGES (comin' up comin' up) THIS IS THE WAY I WANNA LIVE

That's lyrics from an E-type song btw...

Ace
+1  A: 

Someone's name or initials, and that's it. Sometimes these signatures define a block of code...

//SFD Start
...code...
//SFD End

Like the code is such a work of art they have to sign it! Plus, what if someone else needs to change code marked this way?

This should not be confused with the "blame" or "annotate" feature in source control systems - they rock!

Aardvark
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...
JohnFx
A: 

Top of the Pops surely has to be

//  This code should never be called
endian
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.
Konrad Rudolph
// This comment should never have been written.
JohnFx
A: 

My favorite from when I worked on a legacy communications application.

// Magic happens here...
Thomas DeGan
+2  A: 
#include <stdio.h>
//why isn't this working!

With a c-compiler that only supports /*-style */ global comments.

rlb.usa
+4  A: 

One I've never found very helpful:

<!--- Lasciate ogne speranza, voi ch'intrate --->
Soldarnal
Translation? Google's Italian-English only gets about half of it. Is it something like "abandon all hope, ye who enter here"?
GalacticCowboy
Yeah, you're correct.
Soldarnal
Dante - http://en.wikipedia.org/wiki/Divine_Comedy
Abizern
+1  A: 

Ran across a doozy today. I should have expected it given that it was part of a VBA macro in an excel workbook.

a.writeline s 'write line

I found it particularly charming that whomever wrote this took the time to write a comment that used a space to clear up the incredibly confusing jumbled together "writeline" command, but didn't find it necessary to use meaningful variable names. Best I can tell a is short for "a file", and s is short for "a String" (because "a" was already taken).

JohnFx
+1  A: 

Randomly, in the middle of code:

//???
Greg
Place marker. I've done similar things--but it shouldn't be left there!
Loren Pechtel
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.
David Thornley
A: 

Came across this one today:

/// <summary>
/// The Page_Load runs when the page loads
/// </summary>
private void Page_Load(Object sender, EventArgs e) {}
Gavin Miller
+1  A: 
if (someFlag)
{
    // YES
    DoSomething();
}
else
{
    // NO
    DoSomethingElse();
}

There was one guy who did that constantly, the rest of the team eventually convinced him to stop doing it!

Antony Scott
Yeah, just change someFlag to isTrue or something like that.
John at CashCommons
+2  A: 

I'm suprised nobody posted one like this before.

 #contentWrapper{
  position:absolute;
  top: 150px; /*80 = 30 + 50 where 50 is margin and 30 is the height of the header*/
 }

Plain wrong comments are the worst kind of comments.

Pim Jager
+9  A: 

I saw this comment yesterday in a C# app:

//TODO: Remove this comment.
Mike C.
It's like the low-hanging sign telling you to watch out for low-hanging signs.
Mark
A: 

// Good luck

Alex
A: 

Another one I remember:

//TODO: This needs to be reworked.  THIS CRAP NEEDS TO STOP!!!
Mike C.
+1  A: 

Excessive redundancy doesn't clarify what's going on. This one is from mobile phone firmware

/*========================================================================

FUNCTION 
    DtFld_SetMin

DESCRIPTION
    This local function sets a nMin member of the Dtfld struct.

DEPENDENCIES
    None

ARGUMENTS
    [in]me
        Pointer to the Dtfld struct.
    [in]val
        Value to set

RETURN VALUE
    None.

SIDE EFFECTS
    None

NOTE
    None
========================================================================*/
/**
 @brief This local function sets a nMin member of the Dtfld struct..
 @param [in] me  Pointer to the Dtfld struct.
 @param [in]val Value to set
 @retval None 
 @note None
 @see None
*/

static __inline void DtFld_SetMin(DtFld *me, int val)
{
  me->nMin = val;
}
jonny
+3  A: 

We are maintaining terrible mess of PHP application and the original developer had a habit of leaving 'debugging code' commented out in the place. As he always said, it was because "in case he ever needs them again, he just uncomments them and voila, so it saves him a lot of work".

So all the scripts are literally riddled with lines like:

//echo "asdfada";
//echo $query."afadfadf";

None of them is actually functional in any way. They are mostly there to confirm that code execution reaches that point.

On a related note, he never deleted any obsolete script or database table. So we have directories filled with files like dosomething.php, dosomething1.php, dosomething1.bak, dosomething1.bak.php etc... Everybody scared to delete anything because nobody knows, what is really used.

Josef Sábl
that's what version control is for.
Mark
Yeah, but tell it to the author of the scripts I am mentioning.
Josef Sábl
+1  A: 

This:

Yup, a blank space, left as a subversion change log.

Stefan Kendall
+3  A: 
/// <summary>
/// Disables the web part. (Virtual method)
/// </summary>
public virtual void EnableWebPart() { /* nothing - you have to override it */ }
iulianchira
Is this C++? Should be made pure virtual.
Mark
+2  A: 

I work in two languages, (English and French) but my favorite comment was in french:

/* La passe du coyote qui tousse */

Translated it would gives something like this:

/* The coughing coyote trick */

It usually represented a segment of code that either seemed like a clever idea to the author and was completly obscure or it was a weird bugfix that even the author did not understand why it worked (think fixing a race condition by moving if statements around). In all cases it was poorly written code that scared anybody who had to refactor it because it was very hard to predict the effect of changing it.

Pierre-Luc Simard
A: 
{
    Long complicated code logic  //Added this
}
Kapsh
+1  A: 

I found this in a sample application for a mapping product:

// Return value does not matter
return 0;
Nathan W
A: 

I found this in a twisted program

# Let them send messages to the world
#del self.irc_PRIVMSG  # By deleting the method? Hello?
vikingosegundo
+1  A: 
/**
 * Implements the PaymentType interface.
 */
public class PaymentTypePo implements PaymentType
andersonbd1
+7  A: 

AHHHRRRGGHHH Just found this in some ancient code, bet the guy thought he was pretty funny

private
  //PRIVATE means PRIVATE so no comments for you
  function LoadIt(IntID: Integer): Integer;
Peter Turner
+6  A: 

I just found this one, written on the line before a commented-out line of code:

//This causes a crash for some reason. I know the real reason but it doesn't fit on this line.
snicker
Fermat's last comment, apparently.
John at CashCommons
Haha! I hadn't thought of that. Perfect
snicker
+1  A: 

I once worked with a very talented assembly language programmer who had augmented the basic ARM instruction set with a number of macros. His code was made up of tens of thousands of instructions and looked something like the following - with macro instructions that I (a competent ARM programmer) couldn't read represented by ??? and an occasional regular ARM instruction like ADD:

...
??? R0,R0,#1
??? R0,R1
ADD R0,R0,#6    ; Add 6
??? R1,R0
??? R0,R0,R1
...

I can only presume that when you have a brain the size of a planet, it is too high brow to cope with those pesky instructions that are just too damn simple.

Jason Williams
+1  A: 

Found this one today in the middle of a block of declarations:

// other variables

Gee, really? Thanks.

JohnFx
+2  A: 
add ax,1 ;add 1 to the accumulator

seriously? that comment wasted 5 seconds of my life.

also outdated comments FTL

//the system can only handle 5 people right now. make sure where not over
if(num_people>20){
Earlz
A: 

{Some Code;} // I don't Remember why I do this, but it works...

hminaya
A: 

Actually I have a few of these,

// 18042009: (Name here) made me do this

Not very proud of those comments but I keep them to remind me why I did WTF code that particular section, so useful in that aspect.

Makach
A: 

I one time came across this little beauty in a VB.NET app

Dim huh as String 'Best name for a variable ever.
jlech
A: 

I recently found this in some code I wrote aeons ago:

// it's a kind of magic (number)
$descr_id = 2;
$url_id = 34;
DisgruntledGoat
A: 

// return

return;

Eli
+1  A: 

Just found this one today...

// TODO: this is basically a copy of the code at line 743!!!
mezoid
A: 

This comment was actually written in a different language, but I'll try to get the effect across in a translation:

//we trick it, if forbidden, as if it had already existed

What the comment was trying to describe was the way it was dealing with list items that were turned off - the code marked the item as a duplicate which should therefore be skipped. Yes, a very bass-ackwards way of doing things, but it paled in comparison to the nonsensical comment.

Martha
A: 
[some code]
// [a commented out code line]
// this line added 2004-10-24 by JD.
// removed again 2004-11-05 by JD.
// [another commented out code line]
[some more code]

a) WHY? b) Which line?

whybird
+1  A: 

One of the funniest I have ever come across.

// HACK HACK HACK. REMOVE THIS ONCE MARLETT IS AROUND

One that made me wonder.

// this is a comment - don't delete
Secko
+1  A: 

This is a comment I wrote in a file in my group's final project in college

/* http://youtube.com/watch?v=oHg5SJYRHA0 */
Zurahn
-1 offensive. jk.
tsilb
+1  A: 

A classic that we always joke about at my job (complete with typos):

// Its stupid but it work

This was found multiple times in an old code base.

David Thibault
A: 

I saw an awesome code inside the AI part of a game:

..."AI code"...
if(something)
   goto MyAwesomeLabel;   //Who's gonna be the first to dump crap on me for this?
..."More Ai code"...

MyAwesomeLabel:
   //It wasn't that hard to get here, right?
   ..."Even more AI code"...
Seth Illgard
A: 

I had to fix a bug in 2000 lines of code that transcoded audio from GSM into mu-law (mostly using bit shifting and arrays of conversion values). The only comment in the file was at the top of the only method defined in it. It was:

/* Do the business */
Dan J
+1  A: 

// Undocumented

Longpoke
+1  A: 

I was once maintaining the operating system code we customized for a Harris minicomputer (yes, this was a long time ago). Going through the scheduler code (assembler) one day, I came across a code block that had the comment "Begin Magic" at the top and about 25 lines later the comment "End Magic." The code in-between was some of the tightest, most complicated, elegant code I've ever seen. It took 4 of us to figure out what that little section of code was actually doing (VM switching).

jfawcett
+1  A: 
// yes, this is going to break in 2089, but, one, I'll be dead, and two, we really ought to be using
// a different system by then
if (yearPart >= 89)
{
    // naughty bits removed....
}

(Not useful as comments go, but both are truthful statements.)

Michael Todd
A: 

//URGENT TODO: Reimplement this shit, the old code is as broken as hell... and we tought we solved all the problems

Just found that in one of my old projects. At first I laughed but in the end I was bitching because I still couldn't find the bug.

Dr.Optix
A: 

# Below is stub documentation for your module. You'd better edit it

Pestilence
+1  A: 
// initialise the static variable to 0
count = 1;
Evgeny
A: 

I'm making some changes in a java class that has more than 1000 lines but without any comments. I'm newbie in their coding style so i can't help myself about adding a comment like

/*Added because someone asked me to add it*/
dagofly
+3  A: 
if (returnValue ==0)
  doStuff();
else
  System.out.println("Beware of you, the Dragons are coming!");
greuze
A: 

I just saw this in an INI file for a software (one of several dumped on me not long ago) I'm maintaining:

;--- if LOGERR=1, errors are logged but debugging is difficult
;--- if LOGERR=0, errors are not logged but debugging is easy
LOGERR=1

Well, debugging was indeed difficult, but I did not dare change the setting.

MPelletier
A: 

Not quite fitting to the question, but I hate when I see:

try
{
  someSeeminglyTrivialMethod();
}
catch (Exception e)
{
  //Ignore. Should never happen.
}

Whenever I see that during a code review, I tell them to replace the catch with:

catch (Exception e)
{
  System.exit(0);
}
Snekse