What is the best comment in source code you have ever encountered?
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. – DevinB Mar 6 '09 at 15:09
-
2
-
3The 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
-
4total_hours_wasted_here=-32768, what should i do? i think something is broken. – Behrooz Sep 13 '10 at 8:14
-
8Please 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
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... – Daren Thomas Apr 20 '09 at 11:17
-
37Literally did LOL at the combined cleverness and childishness of this one. – David Koelle Apr 22 '09 at 15:07
-
2class MonkeyPoo extends Exception {}; ... throw new MonkeyPoo(); // because it's so much more fun to throw than an exception – Adam Rosenfield Jun 11 '09 at 18:56
-
2
-
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..." – Frank Farmer Jan 3 '10 at 10:23
//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. – Edwin Jarvis Dec 5 '08 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. – Kevin May 13 '09 at 18:20
stop(); // Hammertime!
-
8I like it. Da da da DA, da DA, da DA, It's over (David Spade, SNL, Weekend Update) – MrBoJangles Oct 11 '08 at 18:37
-
83
-
24
-
2
-
2stop(); //! In the name of love. Before you break my heart. – user63904 Nov 7 '09 at 12:02
This seems to stop morons from messing my code...
// Autogenerated, do not edit. All changes will be undone.
-
7
-
3
-
@alex, well duh, now... Anyway, I meant same as you can mark a question as favorite... – AviD Apr 14 '10 at 4:54
-
-
3I think they'll mess your code up anyways: it says it'll fix itself, so why not break it for kicks? – Mateen Ulhaq Jul 1 '11 at 3:35
// sometimes I believe compiler ignores all my comments
-
26
-
86
-
40
-
52laughter, that's the future, compilers reading comments just to make sure they haven't misunderstood ;-D – sharkin Jan 28 '09 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.
-
169
-
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 P Mar 26 '09 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. – Jamol Dec 16 '09 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. – willasaywhat Oct 8 '08 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. – JosephStyons Oct 9 '08 at 3:48
-
56
-
5PLEASE DO NOT ROLLBACK TO NSFW VERSION - the author explicitly accepted the SFW version at revision 3 and 6. – Adam Davis Apr 23 '09 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. – JoshJordan Mar 31 '09 at 6:49
-
22
-
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!" – ivan_ivanovich_ivanoff Apr 15 '09 at 8:33
-
14ha ha, "..somehow a B.A.C. between 0.129% and 0.138% confers superhuman programming ability..." xkcd.com/323 – Alpha Codemonkey Jan 9 '10 at 22:21
// Magic. Do not touch.
-
20
-
44
-
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!" – Shalom Craimer Jan 20 '09 at 14:43
-
6
-
4I still remember being taught CS in high school, where our stupid questions were answered with "Magic!" and the most sinister smile. – nevets1219 Apr 19 '09 at 4:06
#define TRUE FALSE
//Happy debugging suckers
-
95
-
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
) – Chris Lutz Jul 28 '10 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. – rix0rrr Sep 17 '10 at 8:45 -
6
// I'm sorry.
-
179
-
20
-
33
-
52This should be a standard comment in the default templates generated by MSFT – Alexandre Brisebois Oct 9 '08 at 13:40
-
1
return 1; # returns 1
-
32
-
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. – Beep beep Apr 11 '09 at 18:49
-
88
/* This is O(scary), but seems quick enough in practice. */
followed by four nested for-loops
-
33
-
14I once hit a situation with loops nested 8 deep. The runtime was measured in hours. – Loren Pechtel Oct 19 '08 at 19:51
-
8I had a O(n) algorithm with a 500ms network RTT in its inner loop. n > 100k. Ouch. – geofftnz Feb 13 '09 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 – Jon Smock Apr 4 '09 at 18:51
-
27
// Replaces with spaces the braces in cases where braces in places cause stasis
$str = str_replace(array("\{","\}")," ",$str);
-
34
-
71
-
11
-
88Just opened the comments to say that it needs two more syllables, but apparently I beat myself by three months. – Michael Myers♦ Aug 5 '09 at 17:44
-
15I disagree with the need to additional syllables, the meter is perfect as is. Five groups of three syllables each. – KevDog Dec 31 '09 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...
-
67
-
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. – crystalattice Oct 18 '08 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. – Mark Brittingham Dec 15 '08 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. – Danita Mar 26 '09 at 16:45
long john; // silver
-
6
-
6
-
22
-
12
-
1Damn, I was thinking of en.wikipedia.org/wiki/Long_John_Silver's Ether way, I'm hungry. – Tek Jan 25 '11 at 18:52
Catch (Exception e) {
//who cares?
}
/**
* 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 :) – gbjbaanb Mar 29 '09 at 14:28
-
-
5Things like this actually happen, people don't bother keeping documentation up to date with changes even if it's right above the function. – Henk Apr 23 '09 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. – Mark Brittingham Dec 15 '08 at 15:39
-
-
6@Mark He only said he'd optimize the time, he said nothing about the functionality =P – DevinB Mar 6 '09 at 14:33
-
98If it doesn't have to work, I can optimize any code to a runtime of zero. – Michael Borgwardt Apr 3 '09 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. – Kibbee Apr 23 '09 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... – Troy Howard Dec 5 '08 at 19:54
-
32
-
15If you have a System.exit() call in the try block, then YES, the finally should never happen ! – Romain Linsolas Feb 6 '09 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... – Kim Reece Apr 21 '09 at 2:18
-
66s/PSD/Internet Explorer/g. s/file format/web browser/g. Now it matches my thoughts. – TJ L Apr 23 '09 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. – Microkernel Jun 3 '10 at 6:55
-
4This line: // PSD is not my favourite file format. makes this a classic. – joedevon Sep 23 '10 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. – Martin Beckett Apr 20 '09 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! – Josh Apr 5 '10 at 22:10
-
Urgh. A loud "FAIL!" to the author for not knowing if he's using a format-free language or not. – TheBlastOne Sep 1 '10 at 13:24
-
I doubt that he didn't know about the format-free language. That's a nice joke :-) – Román Sep 23 '10 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. – rjzii Oct 9 '08 at 2:47
-
78
-
1
-
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. – Dana the Sane Apr 21 '09 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 – user1228 Mar 5 '09 at 14:45
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 – Juliano Sep 7 '09 at 3:57
-
Makes me think about the far vs. near pointers we used in 16-bit land. :) – Macke Sep 28 '10 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. – tchrist Nov 20 '10 at 1:10
//This code sucks, you know it and I know it.
//Move on and call me an idiot later.
-
26
-
46
-
2
-
// 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. – DNS Mar 6 '09 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. – Charlie Flowers Mar 27 '09 at 7:12
-
23
-
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. – Tgr May 31 '10 at 10:43