What is the best comment in source code you have ever encountered?

share

closed as not constructive by Bill the Lizard Aug 4 '11 at 12:13

As it currently stands, this question is not a good fit for our Q&A format. We expect answers to be supported by facts, references, or expertise, but this question will likely solicit debate, arguments, polling, or extended discussion. If you feel that this question can be improved and possibly reopened, visit the help center for guidance. If this question can be reworded to fit the rules in the help center, please edit the question.

518 Answers 518

From: https://github.com/zepouet/Xee-xCode-4.5/blob/master/XeePhotoshopLoader.m#L108

// At this point, I'd like to take a moment to speak to you about the Adobe PSD
// format. PSD is not a good format. PSD is not even a bad format. Calling it
// such would be an insult to other bad formats, such as PCX or JPEG. No, PSD
// is an abysmal format. Having worked on this code for several weeks now, my
// hate for PSD has grown to a raging fire that burns with the fierce passion
// of a million suns.
//
// If there are two different ways of doing something, PSD will do both, in
// different places. It will then make up three more ways no sane human would
// think of, and do those too. PSD makes inconsistency an art form. Why, for
// instance, did it suddenly decide that *these* particular chunks should be
// aligned to four bytes, and that this alignement should *not* be included in
// the size? Other chunks in other places are either unaligned, or aligned with
// the alignment included in the size. Here, though, it is not included. Either
// one of these three behaviours would be fine. A sane format would pick one.
// PSD, of course, uses all three, and more.
//
// Trying to get data out of a PSD file is like trying to find something in the
// attic of your eccentric old uncle who died in a freak freshwater shark
// attack on his 58th birthday. That last detail may not be important for the
// purposes of the simile, but at this point I am spending a lot of time
// imagining amusing fates for the people responsible for this Rube Goldberg of
// a file format.
//
// Earlier, I tried to get a hold of the latest specs for the PSD file format.
// To do this, I had to apply to them for permission to apply to them to have
// them consider sending me this sacred tome. This would have involved faxing
// them a copy of some document or other, probably signed in blood. I can only
// imagine that they make this process so difficult because they are intensely
// ashamed of having created this abomination. I was naturally not gullible
// enough to go through with this procedure, but if I had done so, I would have
// printed out every single page of the spec, and set them all on fire. Were it
// within my power, I would gather every single copy of those specs, and launch
// them on a spaceship directly into the sun.
//
// PSD is not my favourite file format.
share
66  
s/PSD/Internet Explorer/g. s/file format/web browser/g. Now it matches my thoughts. – tj111 Apr 23 '09 at 18:07
10  
I pity that programmer for having to go through such a pain!!! But awesome piece of comment. Has poured his heart out. – Microkernel Jun 3 '10 at 6:55
14  
PSD, bah! The author has never seen DICOM. – Chris O Jul 28 '10 at 1:51
8  
I didn't know you could fax a blood signature... Have to try this now. – ikdc Aug 26 '10 at 16:19
42  
I like the informative statement at the end! – Muhammad Alkarouri Sep 11 '10 at 0:45

I am particularly guilty of this, embedding non-constructive comments, code poetry and little jokes into most of my projects (although I usually have enough sense to remove anything directly offensive before releasing the code). Here's one I'm particulary fond of, placed far, far down a poorly-designed 'God Object':

/**
* For the brave souls who get this far: You are the chosen ones,
* the valiant knights of programming who toil away, without rest,
* fixing our most awful code. To you, true saviors, kings of men,
* I say this: never gonna give you up, never gonna let you down,
* never gonna run around and desert you. Never gonna make you cry,
* never gonna say goodbye. Never gonna tell a lie and hurt you.
*/

I'M SORRY!!!! I just couldn't help myself.....!

And another, which I'll admit I haven't actually released into the wild, even though I am very tempted to do so in one of my less intuitive classes:

// 
// Dear maintainer:
// 
// Once you are done trying to 'optimize' this routine,
// and have realized what a terrible mistake that was,
// please increment the following counter as a warning
// to the next guy:
// 
// total_hours_wasted_here = 42
// 
share
25  
How am I supposed to get Rick A. out of my head. You better start running... – EricSchaefer Feb 2 '09 at 12:39
321  
I love that "total_hours_wasted_here = 16." I'm going to have to use that in my code :) – Bernard Igiri Feb 2 '09 at 20:56
3  
The first time I've ever been truly RickRolled - and it was funny. When I see links to YouTube I always expect to be RickRolled (camel cased English!!), but I never never never expected to be RickRolled in code comments. – Vincent McNabb Jul 28 '10 at 8:16
4  
total_hours_wasted_here=-32768, what should i do? i think something is broken. – Behrooz Sep 13 '10 at 8:14
8  
Please stop "updating" the counter. It's not worth bumping this question onto the front page yet again. – Michael Myers Sep 23 '10 at 20:30

//The below code needs to be commented out.

share
//Dear future me. Please forgive me. 
//I can't even begin to express how sorry I am.  

And I just found this one today:

//private instance variable for storing age
public static int age;
share
3  
I'm always leaving comments for myself in the future... – David A Gibson Apr 14 '09 at 14:39
26  
Future-self is who your comments should be written for anyway. – Commander Keen Apr 20 '09 at 10:50
    
In regards to the second comment, the programmer didn't explain what type of variable it is. Sloppy. – user43040 Feb 13 '10 at 9:05
1  
@abrereton - obviousily it is a double, its bad form to put such redundant data in the comment – Felan Sep 21 '10 at 17:14
9  
Future-self hates me, and it's not even my fault. It's all Past-self's fault, damn him!! – Sebastián Grignoli Sep 28 '10 at 13:58

When coding MAPPER Apps we had some standards and one of these was that there was a list of standard variables in use throughout the suite. One of these - 'V43' was always used to hold a Surname. So imagine my annoyance when the only comment in a big cryptic chunk of MAPPER code I'd been asked to fix was:

Here V43 contains the Surname
share
/*
* Wirzenius wrote this portably, Torvalds fucked it up :-)
*/
share

Some old fortran code I saw:

     integer *4 one,two,three;

c    asssign one to 100 before entering the loop
     one=100;
share
On error resume next 'because nothing will ever go wrong!
share
// Oh crap, i think i'm gonna yack

followed shortly thereafter by:

// TODO: end this lunacy
share
// long live COM'n'Roll
public enum StatusCode
{
        //success codes
        S_OK                                            = 1,
        S_NONE                                          = 2,
        S_SQL_OPERATIONS_LISTS_EMPTY                    = 3,

        //error codes
        E_NO_MATCHING_END_FOUND                         = -1,
        E_SEQUENCE_NUMBER_NOT_FOUND_AT_BEGINNING        = -2,
        E_SEQUENCE_NUMBER_NOT_FOUND_AT_END              = -3,
        E_FORWARD_AND_BACKWARD_OPS_COUNT_DO_NOT_MATCH   = -4,
        E_FORWARD_AND_BACKWARD_IDS_DO_NOT_MATCH         = -5,
        E_IDS_DO_NOT_MATCH                              = -6
}
share
REM Don't delete this print statement ****** will die

The process in question was a service in some legacy code

share
[vrk:Cloud ID="cTags" runat="server" DataTextField="Tag" DataWeightField="Total"
    Width="100%" DataHrefField="Tag" DataHrefFormatString="~/tags.aspx?tag={0}"]
[/vrk:Cloud]

[!--if anybody would like to change the control's color contact with FLORJON--]
share

First at the beginning of an Update to a huge object:

/*General note to all who tread in the <ObjectName>() code...
 * The SetOriginals() method from the BaseEntity class should be called (and only called) right after the Get() method
 * call as seen above.  Calling the SetOriginals method elsewhere will result in bugs and all kinds of other nasty suprises.
 */

Then after some 200 lines of logic to update the object:

//Attempt to explain this confusing mess of code:
//First time you save an actual absence this is what happens:
//0. The first save saves to the <TableName> table (among other things). (Fig. A)
//1. The <CalculationMethod> method is called next which inserts to the <OtherTableName> table. 
//(This is the table that keeps track of credits to the case.) (Fig. B)
//2. So then you have to call <UpdateCalculations> to move the <TableName> records to the <ThirdTableName> table. (Fig. C)
//3. Then you go back and run calculations since you have the debits table (<ThirdTableName>) populated. (Fig D.)
//4. Then a final save to save the calculations back to the case. (Fig. E)
//Yeah, I know what you're thinking:  this sucks. 10/01/07 XXX

And the developer was right... This sucked HARD!

share
// Holy moses! I've never seen anything so ridiculous in all my life. 

// Why do we need to query the AlarmIDs table twice.

// Please tell me sir; I would really like to know. 

// This like all the other services have been mangled

// to the point where they are nearly impossible to determine what kind of side affects might occur.

// I am making the smallest changes I can to this code. 

// The GetAlarmId method gets the alarm id from the AlarmIDs table.

// Novel idea, why didn't we query for the values be get below all in the same place.

// This should be changed, but right now it will have to remain as is due to time constraints.

// This like all other services really don't do anything fantastically hard, but after the original coders got

// done with them; they are difficult to work with and have an acceptable comfort level.
share
// simply copied from another code
share

I often found this one

// fix it!
share

I've just placed this comment:

// this control (Resistance) is FUTILE! 
share
// repopulate, slight hax (or strong assumptions :P) below
share
private int mousycounter = 0; //Not really a counter
share
What do you think you're doing, Dave?
share
$dnstime = time() + 60 * 60 * 24 * 7 * 2; //how long are you staying for vacation on mars? twooo weeeeeks. give dees people air
share
// This interface defines method signatures<br>
interface IWhatever { ... }
share
// barcore.cpp - MFC

//.....
HBRUSH CControlBar::OnCtlColor(CDC* pDC, CWnd* pWnd, UINT nCtlColor)
{
    LRESULT lResult;
    if (pWnd->SendChildNotifyLastMsg(&lResult))
        return (HBRUSH)lResult;     // eat it

//......

// Eat it - just like eat this.
share

BerkeleyDB

/*
 * Chaos reigns within.
 * Reflect, repent, and reboot.
 * Order shall return.
 */
return (DB_RUNRECOVERY);
share
map(TimeZoneId.Romance, "Romance Standard Time"); //LULZ.
share

at the end of a rather long and convoluted set of while loops and if blocks, the developer in question inserted this final comment:

else
{
    // wobbly wilson said this would *never* happen!!
}

a laconic mixture of wit and sarcasm :)

share

In Latin, Abandon hope all ye who enter here from Dante's "Divine Comedy".

share
7  
Why Latin? the original is Italian... "...Abbandonate ogni speranza, voi ch'entrate." – Adriano Varoli Piazza Dec 30 '08 at 13:42
    
-1 it's a duplicate – bluish Jul 25 '11 at 13:27
// Jay knows what's going on here, but will he remember in a year? Not very likely, this code sucks, but it works so do not change it.

This comment was posted above a huge while-if-for block... Oh, and it manipulated an object array of object arrays of object arrays of strings that could be strings or numbers, depending on at least 3 factors... (yes, I had to debug this code and change it and I wrote the comment, however I did not write the original code). ;)

share
/*
* After 36 hours, 2 holes in my wall and writing my code right beside the API
* this still doesn't work.
* function getMap():void takes in an event object @param: evt:mouseEvent
* I will now retire for the day with a bottle of rum and 2 hours of crying
*/
share

Technically not a comment, but from coding on something at 2 am or so:

consent = False

... that variable is never used again EVER and appears in the beginning of a listen loop for a socket.

share
    
Only 2 of 72? Meh, must not been THAT bad of a bug. – Neil N May 18 '10 at 21:42

Not the answer you're looking for? Browse other questions tagged or ask your own question.