What is the best comment in source code you have ever encountered?
518 Answers
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
//
-
2//Dear Programmer // //Your code now runs slower now that I fixed all the bugs you //introduced. //But your optimizations sure helped.– DevinBCommented Mar 6, 2009 at 15:09
-
-
4total_hours_wasted_here=-32768, what should i do? i think something is broken.– BehroozCommented Sep 13, 2010 at 8:14
-
Best one I've encountered was 2001: 250 x //This is necessary otherwise Netscape will insert multiple linebreaks, honestly!! Commented Sep 18, 2010 at 3:12
-
8Please stop "updating" the counter. It's not worth bumping this question onto the front page yet again.– Michael Myers ♦Commented Sep 23, 2010 at 20:30
Exception up = new Exception("Something is really wrong.");
throw up; //ha ha
-
5I read all comments from top to bottom, wondering what people meant, when they say the "cracked up, reading this one" or "cracked up, reading that one". Well. I just cracked up reading this one... Commented Apr 20, 2009 at 11:17
-
37Literally did LOL at the combined cleverness and childishness of this one. Commented Apr 22, 2009 at 15:07
-
2class MonkeyPoo extends Exception {}; ... throw new MonkeyPoo(); // because it's so much more fun to throw than an exception Commented Jun 11, 2009 at 18:56
-
23When I wake up from truly deep sleep, my IQ drops to about 25, and my mind goes extremely strange places. Once, after a long stint of writing java, I woke up in the middle of the night feeling quite ill, and bolted to the bathroom. As I vomited into the toilet, the only thing I could think was "I wonder which exception I'm throwing right now..." Commented Jan 3, 2010 at 10:23
-
2Would be funnier if the exception message were, "I don't feel so good." Commented Jul 20, 2011 at 15:37
//When I wrote this, only God and I understood what I was doing
//Now, God only knows
-
175That's a phrase from Karl Weierstrass, the mathematician who gave us the wonderful epsilon and delta continuity definition. Commented Dec 5, 2008 at 18:32
-
3
-
4@Augusto, do you have a source for the attribution of that phrase to Weierstrass? I'd like to know what he was referring to.– KevinCommented May 13, 2009 at 18:20
stop(); // Hammertime!
-
8I like it. Da da da DA, da DA, da DA, It's over (David Spade, SNL, Weekend Update) Commented Oct 11, 2008 at 18:37
-
83
-
24
-
2
-
2stop(); //! In the name of love. Before you break my heart.– user63904Commented Nov 7, 2009 at 12:02
This seems to stop morons from messing my code...
// Autogenerated, do not edit. All changes will be undone.
-
3I think they'll mess your code up anyways: it says it'll fix itself, so why not break it for kicks? Commented Jul 1, 2011 at 3:35
// sometimes I believe compiler ignores all my comments
-
26I hope the compiler ignores this person's comments. Commented Oct 14, 2008 at 6:18
-
86// Since I never heard back from the compiler, I believe this is true.– LiwenCommented Dec 18, 2008 at 13:59
-
40
-
52laughter, that's the future, compilers reading comments just to make sure they haven't misunderstood ;-D– sharkinCommented Jan 28, 2009 at 12:03
-
4
// I dedicate all this code, all my work, to my wife, Darlene, who will
// have to support me and our three children and the dog once it gets
// released into the public.
-
169Is this somewhere on the Duke Nukem Forever source code? ;) Commented Oct 10, 2008 at 20:43
-
1
-
11He's dedicating the code below to his wife, even though he knows it's so bad that it's going to either get him fired or make his company go out of business. :)– Robert PCommented Mar 26, 2009 at 16:44
-
390
-
1@Nosredna, thank you for such a funny comment! @hasen j, the code was written so bad that the "programmer" will most likely lose his job, and therefore his wife will have to support the family.– JamolCommented Dec 16, 2009 at 14:18
//Code sanitized to protect the foolish. using System; using System.Collections.Generic; using System.Text; using System.Reflection; using System.Web.UI; namespace Mobile.Web.Control { /// <summary> /// Class used to work around Richard being a fucking idiot /// </summary> /// <remarks> /// The point of this is to work around his poor design so that paging will /// work on a mobile control. The main problem is the BindCompany() method, /// which he hoped would be able to do everything. I hope he dies. /// </remarks> public abstract class RichardIsAFuckingIdiotControl : MobileBaseControl, ICompanyProfileControl { protected abstract Pager Pager { get; } public void BindCompany(int companyId) { } public RichardIsAFuckingIdiotControl() { MakeSureNobodyAccidentallyGetsBittenByRichardsStupidity(); } private void MakeSureNobodyAccidentallyGetsBittenByRichardsStupidity() { // Make sure nobody is actually using that fucking bindcompany method MethodInfo m = this.GetType().GetMethod("BindCompany", BindingFlags.DeclaredOnly | BindingFlags.Instance | BindingFlags.Public | BindingFlags.NonPublic); if (m != null) { throw new RichardIsAFuckingIdiotException("No!! Don't use the fucking BindCompany method!!!"); } // P.S. this method is a joke ... the rest of the class is fucking serious } /// <summary> /// This returns true if this control is supposed to be doing anything /// at all for this request. Richard thought it was a good idea to load /// the entire website during every request and have things turn themselves /// off. He also thought bandanas and aviator sunglasses were "fuckin' /// gnarly, dude." /// </summary> protected bool IsThisTheRightPageImNotSureBecauseRichardIsDumb() { return Request.QueryString["Section"] == this.MenuItemKey; } protected override void OnLoad(EventArgs e) { if (IsThisTheRightPageImNotSureBecauseRichardIsDumb()) { Page.LoadComplete += new EventHandler(Page_LoadComplete); Pager.RowCount = GetRowCountBecauseRichardIsDumb(); } base.OnLoad(e); } protected abstract int GetRowCountBecauseRichardIsDumb(); protected abstract void BindDataBecauseRichardIsDumb(); void Page_LoadComplete(object sender, EventArgs e) { BindDataBecauseRichardIsDumb(); } // the rest of his reduh-ndant interface members public abstract string MenuItemName { get; set; } public abstract string MenuItemKey { get; set; } public abstract bool IsCapable(CapabilityCheck checker, int companyId); public abstract bool ShowInMenu { get; } public virtual Control CreateHeaderControl() { return null; } } }
Update: The original author of the code has outed himself so I must give credit where it is due. Dan McKinley left the company I was with shortly after I started, and he talks more about the code, explaining some background and a few more "WTF's" that 'Richard' wrote.
-
27That's riddled with obscenities, but I literally laughed in my cube the entire time reading it. Commented Oct 8, 2008 at 20:25
-
241
-
58Rolled back. We're all adults here. If the original code had been "sanitized", you would never have remembered it enough to post it here. Commented Oct 9, 2008 at 3:48
-
56Will be even funnier if a customer sees the class name in a stack trace.– finnwCommented Oct 10, 2008 at 2:47
-
5PLEASE DO NOT ROLLBACK TO NSFW VERSION - the author explicitly accepted the SFW version at revision 3 and 6. Commented Apr 23, 2009 at 11:54
// somedev1 - 6/7/02 Adding temporary tracking of Login screen
// somedev2 - 5/22/07 Temporary my ass
-
79
-
17
// drunk, fix later
Wish I were kidding. And knowing the developer who wrote the code, I think he meant it literally.
-
258
-
66@Jiminy: Seriously! When I code drunk, I wake up with magnificent code that I, unfortunately, do not understand. Commented Mar 31, 2009 at 6:49
-
22Ohh... If you don't understand it, it has to be magnificent! Commented Apr 6, 2009 at 11:08
-
14haha!!! I made this just for fun: grepped my local subversion repo for 'drunk', and found one commit comment I wouldn't remember: "Works again, somehow. Well... I'm drunk!" Commented Apr 15, 2009 at 8:33
-
14ha ha, "..somehow a B.A.C. between 0.129% and 0.138% confers superhuman programming ability..." xkcd.com/323 Commented Jan 9, 2010 at 22:21
// Magic. Do not touch.
-
20
-
44Reminds me of this: catb.org/esr/jargon/html/magic-story.html Commented Oct 16, 2008 at 19:31
-
5I've had to write that so many times - mostly to remind myself that "If you touch the following code without really knowing what you're doing, bad things will happen!" Commented Jan 20, 2009 at 14:43
-
6@Simon Howard, I'd only not touch it if it said "More Magic"– DevinBCommented Mar 6, 2009 at 14:31
-
4I still remember being taught CS in high school, where our stupid questions were answered with "Magic!" and the most sinister smile. Commented Apr 19, 2009 at 4:06
#define TRUE FALSE
//Happy debugging suckers
-
95#define NULL (::rand() % 2) // would be quite nice aswell Commented Feb 13, 2010 at 9:57
-
33
-
66@Bart: You can't have half parens in your code, but you could do
#define if(x) if(!(x))
(or, more sinisterly,#define if while
) Commented Jul 28, 2010 at 8:49 -
8As given this would actually work though: the comment-till-end-of-line characters make sure that likely lines where this macro is used will not compile. For example:
a = TRUE;
will translate toa = FALSE // Happy debugging suckers;
which will lead to a compile error because the termating;
is now in comments. If you use the block comment/* Eat this */
it will work.– rix0rrrCommented Sep 17, 2010 at 8:45 -
6
#define struct union
is very helpful in memory constrained systems.– mswCommented Sep 18, 2010 at 2:07
// I'm sorry.
-
179
-
20
-
33
-
52This should be a standard comment in the default templates generated by MSFT Commented Oct 9, 2008 at 13:40
-
1
return 1; # returns 1
-
32Classic! But i like this one even better: "i++; // increase i by 1"– steffenjCommented Oct 12, 2008 at 17:10
-
71
-
13
-
6I've seen this a lot. I know a lot of coders who stub out their functions with comments, then fill in the code below/beside each comment. Makes it very easy to write large business functions, but you end up with some rather detailed comments at times. Commented Apr 11, 2009 at 18:49
-
88
/* This is O(scary), but seems quick enough in practice. */
followed by four nested for-loops
-
33pfft, that's only N^4 most likely, no where near as bad as 4^N or N!– tloachCommented Oct 9, 2008 at 13:23
-
14I once hit a situation with loops nested 8 deep. The runtime was measured in hours. Commented Oct 19, 2008 at 19:51
-
8I had a O(n) algorithm with a 500ms network RTT in its inner loop. n > 100k. Ouch.– geofftnzCommented Feb 13, 2009 at 0:48
-
6There is a redeeming quality: they know what big O terminology is at least. Hopefully each loop is running over very small N :-D Commented Apr 4, 2009 at 18:51
-
27I work with somebody who would say, "O(MFG), please" Commented Nov 19, 2009 at 17:49
// Replaces with spaces the braces in cases where braces in places cause stasis
$str = str_replace(array("\{","\}")," ",$str);
-
34+1 - Pure genius. This should go on a t-shirt or something :-)– RookCommented Apr 20, 2009 at 3:37
-
71
-
11
-
88Just opened the comments to say that it needs two more syllables, but apparently I beat myself by three months.– Michael Myers ♦Commented Aug 5, 2009 at 17:44
-
15I disagree with the need to additional syllables, the meter is perfect as is. Five groups of three syllables each.– KevDogCommented Dec 31, 2009 at 18:26
It speaks volumes about our profession that when asked about the "best comment", we all answer with the worst comments we can find...
-
67I completely agree with your comment that comments are rarely needed.– harpoCommented Oct 17, 2008 at 5:45
-
16Depends on the comments. Even "self-documenting" languages can benefit from comments, such as Python. I hate having to slog through the code to figure out what is happening, when a simple sentence can tell me. Commented Oct 18, 2008 at 15:55
-
32I disagree re: comments being unnecessary. There are times when a simple "framing" comment can make sense of a whole slew of code. For example, if you are using a sophisticated algorithm to escape the time complexity of a brute force algorithm, a reference can be essential. Commented Dec 15, 2008 at 15:35
-
83
-
3I couldn't agree more with "Richard E". Comments are meant to tell your future * (coworkers, reviewers, yourself) why did you chose to do things that wicked way instead of another. I'm not for littering comments all over the place, but sometimes they should be mandatory.– DanitaCommented Mar 26, 2009 at 16:45
long john; // silver
-
6
-
6Totally cracked up as well. I think my code now is too boring. Commented Nov 8, 2008 at 21:45
-
22
-
12
-
1Damn, I was thinking of en.wikipedia.org/wiki/Long_John_Silver's Ether way, I'm hungry.– TekCommented Jan 25, 2011 at 18:52
Catch (Exception e) {
//who cares?
}
-
11
-
68I saw the same thing with // move along, nothing to see here. Commented Nov 6, 2008 at 23:41
-
6
-
9Have to admit that I've done this on more than one occasion because sometimes it just doesn't matter. Commented Dec 18, 2008 at 23:31
-
17Wow, I write that comment all the time. I never thought of it as funny, I thought it was a serious statement.– JayCommented Aug 26, 2009 at 14:07
/**
* Always returns true.
*/
public boolean isAvailable() {
return false;
}
Never rely on a comment...
-
85
-
15I believe you meant, "never rely on the code". I'm sure the spec, design and requirements required a return code or true :)– gbjbaanbCommented Mar 29, 2009 at 14:28
-
looks like something you'd see on the techie edition of failblog.org– BobCCommented Apr 3, 2009 at 13:27
-
5Things like this actually happen, people don't bother keeping documentation up to date with changes even if it's right above the function.– HenkCommented Apr 23, 2009 at 16:28
-
25
/*
* You may think you know what the following code does.
* But you dont. Trust me.
* Fiddle with it, and youll spend many a sleepless
* night cursing the moment you thought youd be clever
* enough to "optimize" the code below.
* Now close this file and go play with something else.
*/
-
32Reminds me of a fellow who swore he could optimize a mechanical theorem-proving algorithm I wrote years ago in an AI project. He did improve performance but then the code didn't work...which he swore was my fault. Commented Dec 15, 2008 at 15:39
-
-
6@Mark He only said he'd optimize the time, he said nothing about the functionality =P– DevinBCommented Mar 6, 2009 at 14:33
-
98If it doesn't have to work, I can optimize any code to a runtime of zero. Commented Apr 3, 2009 at 16:04
-
9That's what source control is for. Waste a few hours trying to optimize it, and then if it doesn't work out, just roll back.– KibbeeCommented Apr 23, 2009 at 2:39
try {
} finally { // should never happen
}
-
15
-
17i've seen that comment (and even written it myself) in the past, for things that relalyt shouldn't ever happen (but just in case, here's code to handle the error). The funniest part is that ti's placed in a finally block, which means it should always happen... Commented Dec 5, 2008 at 19:54
-
32
-
15If you have a System.exit() call in the try block, then YES, the finally should never happen ! Commented Feb 6, 2009 at 10:06
-
6
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.
-
1The line right after that and its comment really top the cake. Sanity? What sanity? The format ate it all... Commented Apr 21, 2009 at 2:18
-
66s/PSD/Internet Explorer/g. s/file format/web browser/g. Now it matches my thoughts.– TJ LCommented Apr 23, 2009 at 18:07
-
10I pity that programmer for having to go through such a pain!!! But awesome piece of comment. Has poured his heart out. Commented Jun 3, 2010 at 6:55
-
4This line: // PSD is not my favourite file format. makes this a classic.– joedevonCommented Sep 23, 2010 at 6:45
const int TEN=10; // As if the value of 10 will fluctuate...
-
136
-
13
-
59
-
184
-
18Calling Fortran from C - Fortran only does call-by-reference so you need variables for all constants. Commented Apr 20, 2009 at 16:43
#Christmas tree initializer
toConnect = []
toRead = [ ]
toWrite = [ ]
primes = [ ]
responses = {}
remaining = {}
-
25
-
16OK I am going to use this next time I need four empty arrays and two hashes!– JoshCommented Apr 5, 2010 at 22:10
-
Urgh. A loud "FAIL!" to the author for not knowing if he's using a format-free language or not. Commented Sep 1, 2010 at 13:24
-
I doubt that he didn't know about the format-free language. That's a nice joke :-)– RománCommented Sep 23, 2010 at 12:05
About the middle of a 30 page xslt
<!-- Here be dragons -->
-
8I'm still trying to figure out how to comment an XSLT in a way that makes sense.– rjziiCommented Oct 9, 2008 at 2:47
-
78
-
1Initially I thought of en.wikipedia.org/wiki/21st_Century_Compilers– chakritCommented Apr 20, 2009 at 4:46
-
6@annakata you think that's bad, the other day someone was asking for help dealing with a 31GB xml file. I cried out in anguish. Commented Apr 21, 2009 at 6:17
-
1
in a completely uncommented 2000 line method
{
{
while (.. ){
if (..){
}
for (.. ){
}
.... (just putting in the control flow here, imagine another few hundred ifs)
if(..) {
if(..) {
if(..) {
...
(another few hundred brackets)
}
}
} //endif
(I actually grepped out all the brackets one day just to see how bad it was, and, sans formatting, got this:
{{{{}}{}{}{}{}}{{}{{}{}{}{}{}{}{{}{}}{}{}{{}{}{}{}{}{}{}{}{}{}{}{{}}}{{}{{}}{{{}}}{{}{}{}{}{}{}{}{{}}{}{{{}}{}{{}{}}{{{}}{}{}{}{}}{{}}}{}{{}{}{}{{}{{}}{}}{{}}}{{}}{{}}{{}}{}{{}}{{}}{{}}{{}{}{}}{}{}{{{}}{{}}}{}{}{}{}}{{{}{{}{}{}{{}{}{}{}{}{}}{}}{{}}{{}{}}}{{}}{{}}}{{}}{{}}{}{}{}{}{{}}{{}{}{}{}}}}{}{}}{{}{{{}{}{}{}}}}{{}{{{}}}}{{}{{{}{{}}{}{{}}{}{{}{}}{{}}{}{{}}}{{}}}}{{}{}{}{}{}{{{} {{{{}}{}{}{}{}}{{}{{}{}{}{}{}{}{{}{}}{}{}{{}{}{}{}{}{}{}{}{}{}{}{{}}}{{}{{}}{{{}}}{{}{}{}{}{}{}{}{{}}{}{{{}}{}{{}{}}{{{}}{}{}{}{}}{{}}}{}{{}{}{}{{}{{}}{}}{{}}}{{}}{{}}{{}}{}{{}}{{}}{{}}{{}{}{}}{}{}{{{}}{{}}}{}{}{}{}}{{{}{{}{}{}{{}{}{}{}{}{}}{}}{{}}{{}{}}}{{}}{{}}}{{}}{{}}{}{}{}{}{{}}{{}{}{}{}}}}{}{}}{{}{{{}{}{}{}}}}{{}{{{}}}}{{}{{{}{{}}{}{{}}{}{{}{}}{{}}{}{{}}}{{}}}}{{}{}{}{}{}{{{}{}{{}}{}}}{}}{{}}{{}{}}{{}{{}{{}}}}{{{}{{{}}}}}{{{{{}}}}}{}{}{}{{{{}}}{}{}}{{}{{}}}}{}{{}}{}}}{}}{{}}{{}{}}{{}{{}{{}}}}{{{}{{{}}}}}{{{{{}}}}}{}{}{}{{{{}}}{}{}}{{}{{}}}}
The endif showed up around line 800)
-
180
-
7
-
67
-
8
-
49Cyclomatic complexity level of OH SHIIIIIIIII– user1228Commented Mar 5, 2009 at 14:45
//This code sucks, you know it and I know it.
//Move on and call me an idiot later.
-
26
-
46
-
2The first step to improvement is to acknowledge the deficiency.– icelavaCommented Dec 18, 2008 at 4:24
-
accept your mistakes before others exaggerate them :) Commented Jul 26, 2011 at 17:56
long long ago; /* in a galaxy far far away */
-
1
-
16@Mauris: It was originally a C and C++ extension for 64-bit integers, which many vendors supported. Then C99 and C++0x standardized support for it: en.wikipedia.org/wiki/Long_long– JulianoCommented Sep 7, 2009 at 3:57
-
Makes me think about the far vs. near pointers we used in 16-bit land. :)– MackeCommented Sep 28, 2010 at 18:38
-
1It still works perfectly fine. We first put it in our compiler at Convex about 25 years ago because DMR suggested that that should be the name for our 64 bit-bit ints.– tchristCommented Nov 20, 2010 at 1:10
// If this comment is removed the program will blow up
-
201A long time ago, I accidentally fixed a segfault in Java3D by adding a comment. It was 100% reproducible; if I removed the comment, it crashed. As long as the comment was there, it worked fine. I assume it was some bizarre timing issue, but I never did figure out exactly what was happening.– DNSCommented Mar 6, 2009 at 14:29
-
54
-
16This is sort of like a virus. It contains content meant to protect itself. It is like the junk DNA that is good at getting itself copied. Commented Mar 27, 2009 at 7:12
-
23you should compare the bytecode generated by the 2 versions– JoelFanCommented Jun 14, 2009 at 18:20
-
13It took me half a day once to figure out that ending a C comment with
\
(used to mark which direction we are going in a 2D array) causes the compiler to skip the next line.– TgrCommented May 31, 2010 at 10:43