
What is the best comment in source code you have ever encountered? (2011) - yammesicka
http://stackoverflow.com/questions/184618/what-is-the-best-comment-in-source-code-you-have-ever-encountered
======
fennecfoxen
In a unit test:

    
    
       # And what father is there among you, who,
       # if his son asks for a slice of bread,
       # will offer him a stone?
       # or if he asks for a fish,
       # will instead of a fish offer him a snake?
       
       my $fish = 'one-fish two-fish red-fish blue-fish';
       my $snake = 'oooh! a snake! ooh! snake! ooooooooo!";
    

(Unit test proceeds to insert both $snake and $fish into a cache object, does
a little bit of extra manipulation to recreate the error condition, requests
'fish' back, and -- until the code was fixed -- got the contents of $snake
instead.)

That's right. A successful combination of biblical allusion with Dr. Seuss and
_Badger Badger Mushroom Mushroom_.

------
spatulon
One of those reminded me of the following legend that gets passed around here
at work.

A codebase had been maintained by a single person, who then left the company.
When the other engineers took over responsibility for the project, they
discovered, to their dismay, that it was almost entirely bereft of comments.

Amongst the tens of thousands of lines of code, they found only one comment,
preceding an unintuitive bitmask operation:

    
    
        /* gok */
    

Nobody could work out what on earth "gok" could mean, let alone why the
previous engineer had chosen to leave that comment when they found no reason
to comment any other part of the project.

Years later, somebody bumped into this chap at a conference and managed to ask
him about the project and the significance of "gok."

"Oh, that's easy. It stands for 'god only knows.'".

------
ColinWright
Several of these have just one or two comments - I've made a note of the one
that has the most discussion. But here are some previous submissions:

[https://news.ycombinator.com/item?id=555201](https://news.ycombinator.com/item?id=555201)

[https://news.ycombinator.com/item?id=604463](https://news.ycombinator.com/item?id=604463)

[https://news.ycombinator.com/item?id=620595](https://news.ycombinator.com/item?id=620595)

[https://news.ycombinator.com/item?id=1626686](https://news.ycombinator.com/item?id=1626686)

[https://news.ycombinator.com/item?id=1699760](https://news.ycombinator.com/item?id=1699760)
(Many comments)

[https://news.ycombinator.com/item?id=1805021](https://news.ycombinator.com/item?id=1805021)

[https://news.ycombinator.com/item?id=2566782](https://news.ycombinator.com/item?id=2566782)

[https://news.ycombinator.com/item?id=2791385](https://news.ycombinator.com/item?id=2791385)

[https://news.ycombinator.com/item?id=4838161](https://news.ycombinator.com/item?id=4838161)

[https://news.ycombinator.com/item?id=5140016](https://news.ycombinator.com/item?id=5140016)

[https://news.ycombinator.com/item?id=5379948](https://news.ycombinator.com/item?id=5379948)

[https://news.ycombinator.com/item?id=5978923](https://news.ycombinator.com/item?id=5978923)

[https://news.ycombinator.com/item?id=6232500](https://news.ycombinator.com/item?id=6232500)
(Ask HN, not StackOverflow)

~~~
kbenson
[https://news.ycombinator.com/item?id=2566782](https://news.ycombinator.com/item?id=2566782)
is so meta.

------
sanswork
Ad company I work for buys one of our traffic partners. I'm code reviewing
their system to document it and find a comment describing how they defraud us.

That got awkward fast.

~~~
bookface
That sounds like an interesting story. Are there any more details that you're
willing/at liberty to divulge?

~~~
sanswork
Standard advertising fraud with faking traffic data. I handed it off to my
manager who sent it to the CTO and from there it was dealt with at the
executive level. Not sure all the details but I know the CEO of the other
company went from picking furnishings for a new larger office to packing a box
within a day or two and most of the rest of the acquired company was let go a
short time later.

------
groovy2shoes
Netcat is full of great comments. Here's a good one:

    
    
        /* I really want to strangle the twit who dreamed up all these sockaddr and
           hostent abstractions, and then forced them all to be incompatible with
           each other so you *HAVE* to do all this ridiculous casting back and forth.
           If that wasn't bad enough, all the doc insists on referring to local ports
           and addresses as "names", which makes NO sense down at the bare metal.
           
           What an absolutely horrid paradigm, and to think of all the people who
           have been wasting significant amounts of time fighting with this stupid
           deliberate obfuscation over the last 10 years... then again, I like
           languages wherein a pointer is a pointer, what you put there is your own
           business, the compiler stays out of your face, and sheep are nervous.
           Maybe that's why my C code reads like assembler half the time... */
    

[http://sourceforge.net/p/nc110/code/HEAD/tree/nc110/netcat.c](http://sourceforge.net/p/nc110/code/HEAD/tree/nc110/netcat.c)

~~~
sigil
netcat.c is by _far_ one of the most entertaining code reads out there.
Because of the unix networking / portability rants -- which are sometimes
informative -- and also because the Hobbit was such a strange, scatalogical
creature...

    
    
        grep -in poop netcat.c
    
        110:struct host_poop {
        115:#define HINF struct host_poop
        117:struct port_poop {
        122:#define PINF struct port_poop
        163:HINF ** gates = NULL;		/* LSRR hop hostpoop */
        169:PINF * portpoop = NULL;		/* for getportpoop / getservby* */
        336:   cross-check the host_poop we have so far against new gethostby*() info,
        340:int comparehosts (poop, hp)
        341:  HINF * poop;
        349:  if (strcmp (poop->name, hp->h_name) != 0) {		/* case-sensitive */
        351:  if (strcasecmp (poop->name, hp->h_name) != 0) {	/* normal */
        353:    holler ("DNS fwd/rev mismatch: %s != %s", poop->name, hp->h_name);
        360:/* gethostpoop :
        361:   resolve a host 8 ways from sunday; return a new host_poop struct with its
        365:HINF * gethostpoop (name, numeric)
        371:  register HINF * poop = NULL;
        397:    poop = (HINF *) Hmalloc (sizeof (HINF));
        398:  if (! poop)
        399:    bail ("gethostpoop fuxored");
        400:  strcpy (poop->name, unknown);		/* preload it */
        411:    strncpy (poop->name, hostent->h_name, MAXHOSTNAMELEN - 2);
        413:      memcpy (&poop->iaddrs[x], hostent->h_addr_list[x], sizeof (IA));
        414:      strncpy (poop->addrs[x], inet_ntoa (poop->iaddrs[x]),
        415:	sizeof (poop->addrs[0]));
        418:      return (poop);			/* inverse stuff, we're done. */
        421:    for (x = 0; poop->iaddrs[x].s_addr && (x < 8); x++) {
        422:      hostent = gethostbyaddr ((char *)&poop->iaddrs[x],
        426:	  poop->addrs[x]);
        428:	(void) comparehosts (poop, hostent);
        432:    memcpy (poop->iaddrs, &iaddr, sizeof (IA));
        433:    strncpy (poop->addrs[0], inet_ntoa (iaddr), sizeof (poop->addrs));
        435:      return (poop);
        437:      return (poop);			/* the full DNS hair */
        443:	strncpy (poop->name, hostent->h_name, MAXHOSTNAMELEN - 2);
        444:	hostent = gethostbyname (poop->name);
        447:		poop->name);
        449:	  (void) comparehosts (poop, hostent);
        453:/* whatever-all went down previously, we should now have a host_poop struct
        456:  return (poop);
        457:} /* gethostpoop */
        459:/* getportpoop :
        460:   Same general idea as gethostpoop -- look up a port in /etc/services, fill
        461:   in global port_poop, but return the actual port *number*.  Pass ONE of:
        466:USHORT getportpoop (pstring, pnum)
        476:  portpoop->name[0] = '?';		/* fast preload */
        477:  portpoop->name[1] = '\0';
        495:      strncpy (portpoop->name, servent->s_name, sizeof (portpoop->name));
        509:      return (getportpoop (NULL, x));	/* recurse for numeric-string-arg */
        514:      strncpy (portpoop->name, servent->s_name, sizeof (portpoop->name));
        536:  sprintf (portpoop->anum, "%d", x);	/* always load any numeric specs! */
        537:  portpoop->num = (x & 0xffff);		/* ushort, remember... */
        538:  return (portpoop->num);
        539:} /* getportpoop */
        994:   gethostpoop wants a string and there's much gnarlier code out there already,
        1002:  whozis = gethostpoop (bigbuf_net, o_nflag);
        1451:  portpoop = (PINF *) Hmalloc (sizeof (PINF));
        1545:	gp = gethostpoop (optarg, o_nflag);
        1572:	o_lport = getportpoop (optarg, 0);
        1584:	wherefrom = gethostpoop (optarg, o_nflag);
        1654:    whereto = gethostpoop (argv[optind], o_nflag);
        1669:      curport = getportpoop (argv[optind], 0);
        1713:        hiport = getportpoop (cp, 0);
        1719:    loport = getportpoop (argv[optind], 0);
        1740:      curport = getportpoop (NULL, curport);
        1749:	  whereto->name, whereto->addrs[0], curport, portpoop->name);
        1768:	    whereto->name, whereto->addrs[0], curport, portpoop->name);

------
jpitz
I've commented before that I feel that the PostgreSQL project is especially
wonderful about code comments. According to the cloc tool, their C code has
700k lines of code and 221k lines of comments. That by itself isn't terribly
impressive if you've seen a lot of the typical boilerplate comments a lot of
IDEs place in code, but have a look at a sample of the actual comments :
[https://github.com/postgres/postgres/blob/master/src/backend...](https://github.com/postgres/postgres/blob/master/src/backend/parser/analyze.c)

Thoughtful, meaningful, and high-level. I aspire to this.

------
harrytuttle
The favourite one from our codebase:

    
    
       // And God said: "let there be....shite"!
    

(followed by some C# reflection code to break into a sealed class in the .Net
framework)

All other comments are pointful, well described and useful.

------
__david__
This is a purposefully obfuscated piece of code (the chip manufacturer didn't
want to leak what the bits meant):

    
    
        sBoardWantsEncryption = (x&0x3)!=0x1||(x&0x3)==0x1&&(x&0x3c)!=0x00; // Wheee!
    

Here's a better one from some DDS tape drive firmware:

    
    
        /*  All measurements in 27 MHz ticks
         // PG = Drum PG
         // RG = Read Gate
         // WG = Write Gate
         // BH = B Head
         // 
         // *****************************************************************************
         //  **DDS:
         //       sReadTrackStart          Sync
         //              v                   v 
         //              |  Margin  |Preamble|SubData|...|Subdata|PostAmble|  Margin  |
         //              |<- 3782 ->|<- 688->|                   |<- 343 ->|<- 3782 ->|
         //                    ____________________ . . . ____________________
         //        RG ________|                                               |________
         // WWWWWWWWWWWW
         //              RRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRR
         //                   |<--- ???? --->|
         //                  (gDesiredRGToSync)
         //                 (ArbitrarySyncTime)  
         //                                                                     ~2500
         //              |<---------- 67382.701 nominal (67248 - 67517) ------------->|
         //                                      (From DDS Spec)
         //
         //  W = write track
         //  R = read track
         //  sReadTrackStart is calculated below.
         //  SkipMargin = Margin+Preamble - ArbitrarySyncTime (3300)
         //  ReadGateOn     = sReadTrackStart + Margin+Preamble - ArbitrarySyncTime
         //  ReadGateOff    = sReadTrackStart + SpecTrackLength - (Margin+PostAmble)/2
    

This is another one from the same project that I particularly liked:

    
    
        /* So you want to know the relation between the hardware and the
           software control constants. Well,
    
                           /---/\/\---||---\
                           |    R2     C   |
                      R1   | |\            |
                  e--/\/\----|-\___________|____v
                  2.5v-------|+/
                             |/
    
                    Kh = Ks/(2^ix) = R2/R1
                    Ih = Is/(2^ix)/dt = 1/R1/C
    
                       Capstan         Drum
                   dt  1/1800          1/100
                   ix    Cix            Vix
        */

------
pilif
This tangentially reminds me of the fact that every time I'm writing a comment
that's longer than 4 lines and explaining in detail why the thing following
works as it does, then both the comment and the thing it was explaining won't
survive the next hour.

When you need more than two lines to explain something, then something is
wrong and you'd better fix it.

But maybe the act of writing the comment helps to free the brain to find a
better solution.

This happens to me time and time again.

~~~
robomartin
This is absolutely not true. Perhaps you are not choosing the right time to
sit down and comment. I'll usually put in quick comments as a module is under
construction. Once it reaches stability (meaning, I am moving on to something
else) the detailed comments go in.

Also, if we are talking about embedded there are a lot of comments that are
invariant because they might explain details of the hardware interface this
particular chunk-o-code might be dealing with. That hardware --external to the
chip you are programming-- will not change unless a hardware revision is done,
which is far less frequent than code iterations.

------
6d0debc071
/* Date of comment 17-10-2001

WHY ORDERS ARE VANISHING

You can't see this from just looking at the code: there are four other systems
that interact with the same database. I've managed to localise the problem by
the timing of faults, it seems like Cassandra is erasing entries that aren't
on its local list.

They won't let us change this because they're afraid of breaking the system.

If Alec's still in charge, you're effectively out of luck. If the boss has
changed, try asking about changing it again.

tl-dr: Your princess is in another castle. */

~~~
tazjin
What does Cassandra refer to here? The project now known as Apache Cassandra
had its initial release in 2008.

~~~
6d0debc071
It was just the name of one of the progs interacting with the database, they
called them after figures from Greek mythology.

------
adnam
Before I click, I bet this has been closed as "not constructive".

[edit] Yep.

~~~
maaaats
Letting people ask these questions freely would destroy the community. They
would grab all attention, and the focus would be on creating clever questions
and answers, not providing good help for developers. Kinda how the biggest
sub-reddits work; content that is easy to diggest grows quickly to the top.

~~~
Dylan16807
There's only so many of 'these questions'.

There is _especially_ no harm in letting the historical ones stay open.

~~~
maaaats
And no use in leaving them open as well. What would a new answer buried away
accomplish?

And closing them with the "historical" note makes it clear that similar
questions should not be asked.

------
ScottBurson

      while (read(line, ...) > 0) {
        if (line[0] == '#') continue;   // comment
        ...
      }

------
robomartin
This is one of the things that really bugs me about a lot of open source and
Github code: almost no comments.

It almost seems that there's a generation of programmers being taught that
comments are a waste of time. I really don't know where this trend comes from.
Lazy? I don't want to believe that.

For my purposes it is a huge negative mark if a programmer is not religious
about commenting code. I will not hire someone like that. Why? Developing code
is a huge financial investment, yes, but there are other metrics that are far
more important than money. If you are doing something non-trivial it often
requires a lot of thought, discussion, testing, experimentation, failures,
iterations and decisions. Comments within code should be used to document some
of this. Document intent, thinking, problem solving approach, corner cases,
decisions, where/how it could be improved, performance notes, etc.

This and the code become incredibly valuable. It means that months or years
later someone can go back into the code and truly understand what it does, why
it does it that way, where it came from and, perhaps, how it could be
improved. You don't need to engage in a research project in order to pick-up
where the last programmers left of and continue moving forward. In addition to
that I firmly believe a well-commented code-base is far more valuable during
an acquisition than a thousand files of code with hardly a comment.

I can think of a number of Github projects I've come across with nearly zero
comments. What you are looking at is dozens or hundreds of files vomited upon
your hard drive that, yes, might perform a useful function at that point in
time yet would be a nightmare to dive into to maintain them in any way. Before
someone jumps down my throat: Just because something is FOSS it doesn't mean
we should not critique such practices. If everyone took the time to
thoughtfully document their code the FOSS ecosystem would probably evolve at a
faster rate. Some of these packages are so dense they are virtually
impenetrable without cubic hours of work deciphering the rats nest of files.

~~~
T-hawk
The counterargument is that code should be self-documenting. If code is
complicated enough to need comments, refactor it. Behavior should be obvious
from function and variable names. If you can't say what a method does in its
name, it's too big. The best code transcends the need for comments.

What you describe about the development process, to write down the thinking
and edge cases and decisions and such, is important but doesn't really belong
in the source code. That stuff belongs in your issue tracker system or the
commit messages. What other medium tries to embed a description of the
creative process in the work itself? Da Vinci didn't write on the back side of
the Mona Lisa the production process for his paints. Tolkien didn't explain
how he created the Elvish language in the text of the novels. There's
accompanying material for that.

But realistically for software, that accompanying material is not going to get
read elsewhere, or survive long-term through migrations to different tools and
hosts. So it ends up in the source as the only way to keep it with the code
and visible ten years later. Commenting is a least-bad solution, not a good
one.

And of course, policies for code commenting never work. You just get
scintillating gems like "x+=5; //add 5 to x".

~~~
iloveponies
The idea that code be "self-documenting" is naive at best. Action does not
necessarily infer intention, and without explanation can lead to assumption.
To reach the code we end up committing a process of thought should have
occurred by those who wrote it. For some things such as "boilerplate" code
this may not be seen as significant. For others of increased complexity like
explaining interactions between two pieces of logic, performing a complex set
of logic or the expected usage of an externally provided interface comments
are in my opinion essential.

In contrast to what you've said I completely disagree with the notion that the
"best code transcends the need for comments". I'd argue the best type of code
has the most effective comments in line with code to ensure the next person
can gain with the least amount of effort clear understanding of both the
rationale and of the functionality that lead to what they see before them.

------
VikingCoder

        // Don't remove this comment, or the next line will break.  WTF?!?
    
    

Turns out, we had mixed carriage returns and line feeds in our source. We had
some UNIX coders, and some Windows coders. The Windows coders were in VS6
(ug), and the IDE showed the code perfectly. The compiler, on the other hand,
was getting confused because one file had mixed CR/LF... So, essentially, it
thought

    
    
        // Comment
        formatHardDrive = true;
    

It thought that pesky next line was still part of the comment. It wasn't
literally formatting the hard drive... that was another bug we encountered,
one time... oh, the places you'll go...

------
ja27
I think the best one that I didn't write was a long back-and-forth argument in
a C header file where TRUE was defined as 0 and FALSE as non-zero. The
original author of this product apparently had screaming fights about that
being THE RIGHT WAY. Of course that surprised a lot of developers over the
years and had been "fixed" several times only to be reverted back.

------
jgrahamc
Pretty sad that all these examples are bad comments not good ones.

Here's a comment from some code that I posted to my blog. The idea was that
this would explain in detail to someone reading the code what I was doing with
the pieces of a wooden train set. This was critical to the operation of the
program and I imagined that many of the readers of the code would need a
careful explanation.

It turns out that I'd forgotten what this code does so the comment was
helpful.

    
    
      # The 15 possible pieces: a straight edge (which has $unit length) and
      # is used as the measurement for everything else, a bridge (which is
      # twice the length of the straight edge; it is actually supplied in
      # two pieces but for the purposes of this program is considered to be
      # a single piece) and a curve (using $radians_in_curve above the
      # length of the straight line between the ends of the curve is
      # calculated).
      #
      # Each entry consists of three parts:  
      #
      # length: the length in a straight line between the ends of the piece
      # at its centre. 
      #
      # angle: the angle (in radians) between the straight line through the
      # piece and a tangent to the curve at the piece's start.  This only
      # applies to curved pieces where the straight line is the line joining
      # its two endpoints.
      #
      # count: how many of these pieces are supplied.
      #
      # Note that curves can be placed in either a clockwise or
      # anticlockwise direction. The program detects this by looking at the
      # angle.  If it's non-zero then the piece has two orientations.
    
      my %pieces = (
        Bridge   => { length => $unit * 2,
                      angle  => 0,
                      count  => 1 },
    
        Straight => { length => $unit,
                      angle  => 0,
                      count  => 2 },
    
        # Here's a curved piece, the angle a is $radians_in_curve, the
        # length l of a side is $unit.  So length is the distance between
        # the points labelled s and f. Bisect the angle a you get a right
        # angle triangle with hypotenuse of length $unit and angle at the
        # vertex of $radians_in_curve/2.  So the angle b is $PI/2 -
        # $radians_in_curve/2. By simple trigonometry the length is twice
        # $unit * cos($PI/2-$radians_in_curve/2).
        #
        #                  s
        #                  C
        #               .  .  C
        #             .   b    C
        #         l .       .   C
        #         .              C
        #       .            .   C
        #     .  a               C
        #   .  .  .  .  .  .  . C
        #  o                    f
        #
        # To calculate the angle to the tangent at point s (the angle c),
        # note that the angle formed by os and the tangent is a right angle
        # (since os comes from the centre of the circle).  So b+c is $PI/2
        # but b is $PI/2 - $radians_in_curve/2 and so c is
        # $radians_in_curve/2
        #
        #                  s
        #                  .
        #               .  .  .
        #             .   b  c  .
        #         l .       .     .
        #         .                 .
        #       .            .        .
        #     .  a                      .
        #   .  .  .  .  .  .  .  .  .  .  .
        #  o                    f
        #
    
        Curve    => { length => 2 * $unit * cos($PI/2-$radians_in_curve/2),
                      angle  => $radians_in_curve/2,
                      count  => 16 }
      );
    

[http://blog.jgc.org/2010/01/more-fun-with-toys-ikea-
lillabo-...](http://blog.jgc.org/2010/01/more-fun-with-toys-ikea-lillabo-
train.html)

Interestingly, the first line of this comment contains an error. There are 19
pieces not 15.

~~~
eitally
That's beautiful! I have lately been encouraging all my team to take
advantages of comments to document the high level business logic _as it was at
the time of development._ It provides utility during code review and future
dev, and it's a terrific CYA when debating with stakeholders about what they
said they wanted then versus what they "remember" asking for.

~~~
jgrahamc
That example is particularly verbose because I knew I'd forget it and it
wasn't obvious what I was doing. A clear example of something shorter is:

    
    
      // Briefly the algorithm goes like this:
      //
      // Slide a 16x16 block across the entire image from left hand corner
      // to bottom right hand corner.  For each 16x16 block perform a
      // discrete cosine transform on it and then quantize the 16x16 block
      // using an expanded version of the standard JPEG quantization matrix.
      //
      // Each quantized DCT transformed is stored in a matrix with one row
      // per (x,y) position in the original image (the (x,y) being the upper
      // left hand corner of the 16x16 block being examined.
      //
      // The resulting matrix is lexicographically sorted and then rows that
      // match in the matrix are identified.  For each pair of matching rows
      // (x1,y1) and (x2,y2) the shift vector (x1-x2,y1-y2) (normalized by
      // swapping if necessary so that the first value is +ve) is computed
      // and for each shift vector a count is kept of the number of times it
      // is seen.
      //
      // Finally the shift vectors with a count > some threshold are
      // examined, the corresponding pair of positions in the image are
      // found and the 16x16 blocks they represent are highlighted.
      //
      // Uses the FreeImage library (http://freeimage.sf.net/) to access
      // image data
    

From: [http://blog.jgc.org/2008/02/tonight-im-going-to-write-
myself...](http://blog.jgc.org/2008/02/tonight-im-going-to-write-myself-
aston.html)

------
wrl
I had a line of code in one of my C projects which read:

    
    
        free(self); /* so liberating */

------
pkulak
I've come across this one several times courtesy of
[https://news.ycombinator.com/user?id=aphyr](https://news.ycombinator.com/user?id=aphyr)

    
    
        def self.merge(man)
          # Shock!
          clark_kent = super man

------
peterkelly
"Beware of bugs in the above code; I have only proved it correct, not tried
it."

\- Donald Knuth

------
auvi
I think is the all time classic:

    
    
      /*
      * If the new process paused because it was
      * swapped out, set the stack level to the last call
      * to savu(u_ssav).  This means that the return
      * which is executed immediately after the call to aretu
      * actually returns from the last routine which did
      * the savu.
      *
      * You are not expected to understand this.
      */

~~~
pmiller2
Yep. I did a ^F to see if anyone had posted this one. See [http://cm.bell-
labs.com/who/dmr/odd.html](http://cm.bell-labs.com/who/dmr/odd.html) for an
explanation of this and other great Unix comments. :)

------
_halgari
Back around 2006 was an auto-generated file in Blender 3d's source code, if
you edited it by hand and then ran one of the tools it would spit out a .h
file with the contents:

"NO! YOU FOOL! STUPID, STUPID, STUPID!"

------
ananth99
Exception up = new Exception("Something is really wrong."); throw up; //ha ha

LOL.

------
sturadnidge
From tunefs(1) on older SunOS

    
    
            .\" Take this out and a Unix Demon will dog your steps from now until
            .\" the time_t's wrap around.
            .sp
            You can tune a file system, but you can't tune a fish.

------
slowmover
Back in my heady startup days, I'd occasionally take my programmers to a local
pub for afternoon chat and coding sessions. Code produced during these
sessions often contained comments like:

    
    
      /* First pint begins here */
    
      /* Starting a second pint */
    

The idea being to keep track of code written during increasing states of
inebriation. Interestingly, later analysis of that code showed no relationship
between number of drinks and number of defects. (Of course none of us would
ever get really smashed.)

------
rheide
Comment from a project I used to work on:

    
    
      # Circular references are a pain, yet so easy to avoid,
      # however unpicking them at a later date can be hard
      # and [python module name] especially so.
      # Therefore I shall ignore this for now and use this poor quality
      # botch to stop the code from breaking.
      # I dream of a day in the future when I will be able to remove
      # this crappy hack and the [project name] source code makes the world
      # a better place.
      # Until then I will cry myself to sleep each night.

~~~
_sabe_
There's a lot to be said about programmers, but in how many other professions
do people actually feel like crying for not finding the best solution to a
problem?

~~~
mhurron
Vets? Doctors?

What does a programmer have to cry about?

~~~
moron4hire
I used to work on simulations of industrial lifting cranes. Crane operators
would use the simulator to plan a lift before going out into the field to
execute it. This was 'round about 2008, when New York City had all of those
cranes fall over in one year. Luckily, none of them were any of our customers,
but every day was a new test of patience as we waited on the news to tell us
what company was responsible so we could check out customer list.[1]

I'm now working on DOT road signing systems. The software I am writing will be
used to figure out when and where to put up speed limit and warning signs.

What is really, super concerning is that, though I am capable of doing all of
the math and physics that the job requires (and there is really no reason for
you to believe me on that point, which makes the situation even worse), none
of the other programmers I've ever worked with on these projects could.[2] The
companies that hired me just got lucky that I typically go with the least-
effort job application process and am too lazy to be constantly applying to
jobs. There was no vetting process, it was just "take the cheapest guy we can
get".

When people could die as a direct result of a programming error on your
behalf, it tends to change your perspective on things.

[1] When the company ignored my analysis that certain parts of the data was
logically inconsistent (this system used look-up tables to do everything, very
little was _actually_ simulated), I quit. As far as I was concerned, the fact
that none of our own customers had been in the news was mere luck and I had no
interest in being on watch with my hands tied behind my back when it finally
did happen.

[2] The _most recent_ fun defect I had to fix involved someone having added
two angles together, one in degrees, the other in radians. That prompted this
little thought-experiment in code:
[https://github.com/capnmidnight/UnitsOfMeasure/tree/master/U...](https://github.com/capnmidnight/UnitsOfMeasure/tree/master/UnitsOfMeasure).
It works for some simple things and has an interesting side effect of helping
document the code, which I realized when I failed to convert a particular
poorly documented section of the code to this system.

~~~
unimpressive
> none of the other programmers I've ever worked with on these projects could.

Thank you, this is going into my risk assessment of various dangers.

~~~
moron4hire
You should. We don't certify programmers, so it's a very real risk.

On the other hand, I do not support the efforts of my state to attempt to
license software engineers. As it's written, it really only seems like a
protectionism racket to keep upstarts from competing with established firms.
To whit: employees of S-corps are exempt. Way to miss the entire freaking
point, Virginia.

------
andyjohnson0
/* Here be dragons. */

At the top of the main loop of a heavily multi-threaded, iocp-based socket
server written in K&R-style C. When I refactored it and ported to C++ I left
the comment in.

------
helloTree
There is also a fun part in the documentation of xorg.conf, just do

$ man xorg.conf

and search for "nobody"

;)

------
agrona
Not exactly a comment, but I immediately thought of this:

"Whoa, that’s a full fog all the way. Double fog, oh my god. It’s a double
fog, all the way. Whoa that’s so intense. Whoa man! Wow! Whoa! Whoa! Whoa ho
ho oh my god! Oh my god! Oh my god! Woo! Oh wow! Woo! Yeah! Oh ho ho! Oh my
god! Oh my god look at that! It’s starting even to look like a triple fog! Oh
my god it’s full on! Double fog all the way across the sky! Oh my god. Oh my
god. Oh god. What does this mean? Oh. Oh my god. Oh. Oh. God. It’s so bright,
oh my god it’s so bright and vivid! Oh. Ah! Ah! It’s so beautiful! Oh my god.
Oh my god. Oh my god! Oh my god, it’s a double complete fog! Oh right in my
map. Oh my god. Oh my god, what does it mean? Tell me. Too much. I don’t know
what it means. Oh my god it’s so intense. Oh. Oh. Oh my god." \- Change 533404
by jim on 2010/07/19 18:07:00

[http://www.reddit.com/r/gaming/comments/11mz4k/i_am_a_progra...](http://www.reddit.com/r/gaming/comments/11mz4k/i_am_a_programmer_for_guild_wars_2_amaa/c6nwksr?context=1)

------
mtm
Late one night in the early '80s I was bored and found myself paging through
the code for WordStar (best I can remember) with 'ddt' on my Kaypro. Just page
after page of Z80 disassembly and blocks of data… when suddenly I came across
the words:

    
    
       "Nosy, aren't you?"
    

In my sleep addled state that was one of the funniest things I'd ever seen.

------
srl
Back when I was first learning C++.

    
    
      // This is what I think of websites saying not to use fflush().
      fflush(stdout);

------
techtalsky
I'll always love all the comments that came to light when a significant hunk
of Win2k source code was leaked, especially:

* The magnitude of this hack compares favorably with that of the national debt.

[http://www.kuro5hin.org/story/2004/2/15/71552/7795](http://www.kuro5hin.org/story/2004/2/15/71552/7795)

------
joshuahedlund
Several of the answers revolve around dire warnings to not change or remove
something even though no one may know why. They made me laugh and I've done
similar, but I've also found that sometimes I stumble upon them again a couple
years later and find I now have the skills to understand and optimize the code
without breaking it.

------
habosa
This might be asking for trouble, but what are people's views on comments in
normal cases? I once worked on a codebase where there were no comments, and
people actively worked to remove them. It was a large Java Enterprise codebase
and the idea was that anywhere I wanted to insert a comment, I should refactor
and rename until the code explained itself.

At first this was horrifying, especially when I was thrown into this comment-
free codebase with thousands of files. However it did make me write better
code, knowing that I couldn't rely on comments to explain what I was doing. I
wrote short functions that were easy to understand, and paid attention to all
variable names. It definitely made me a better Java programmer, but outside of
that project I still think comments have huge value. I comment my code a ton,
and I think it makes it better. Anyone else ever worked in a no-comment zone?

~~~
nucleardog
I wouldn't call it a "no comment zone", far from it, but inline comments are
nearly nonexistent where I work.

We write in the same way you did - short methods, lots of classes, descriptive
(but not overly-so) variable names. The code should more or less document
itself.

One place you will find comments are docblock style in projects providing an
external API to allow us to generate the documentation from the code - it's
the easiest way to ensure our docs are up to date.

The other is one or two word comments in the code, usually to avoid overly-
verbose variable names. For instance, a variable named 'distance' might be
immediately followed by 'in meters'.

As an added bonus, it helps make the code testable and improves (at least my)
confidence in the results because complex logic is instead broken into lots of
bits of simple logic which can more easily be thoroughly tested.

------
peter303
Knuth's "Art of Programming" series after 1985. He pretty much writes the
documentation first, embeds the code in the documentation, uses compiler-
preprocessors to extract, join and compile the code. He spent over a decade
writing these tools himself since there wasnt really anything in existance to
do that.

------
api
In a template C++ class called Buffer that supports assignments and
comparisons with other instances templated for different Buffer sizes:

    
    
        // "Learning to love yourself is the greatest love of all." - Whitney Houston
        template <unsigned int C2> friend class Buffer;

------
dmoney

      // Maybe these two lines will crush everything.
    

Whatever it referred to was no longer there.

------
belorn
I used to read the nethack source code comments just for fun. Beyond jokes,
lore, and the numerous not-implemented-yet features, it also included a small
section regarding polymorph in fantasy games.

It asked: how should one handled multi-head/arms creatures? Do they get one
amulet and one helmet per head? What constitute an arm? How many rings should
a 4 armed creature be allowed to wear?

It nice when you see source code that is meant to be read as well as compiled.

------
gprasanth

        /*
        thisIsCodeBlock(1);
        moreCode();
        /*/
        thisIsCodeBlock(2);
        andMore();
        //*/

------
robomartin

        #define REG_08_POWER_DOWN    0x36   //    0011 0110    
                                            //    |||| ||||
                                            //    |||| |||Power Down: 0 = Power down// 1 = Normal operation
                                            //    |||| ||Edge Select: 0 = Falling edge// 1= Rising edge
                                            //    |||| |Input Bus:    0 = 12 bits// 1 = 24 bits
                                            //    |||| Dual edge:        0 = Single edge// 1 = Dual edge
                                            //    |||H-sync enable:    0 = Always low (no H-sync)// 1 = Transmitted
                                            //    ||V-sync enable:    0 = Always low (no V-sync)// 1 = Transmitted
                                            //    Reserved
    
        #define REG_08_NORMAL        0x37   //    0011 0111    
                                            //    |||| ||||
                                            //    |||| |||Power Down: 0 = Power down// 1 = Normal operation
                                            //    |||| ||Edge Select: 0 = Falling edge// 1= Rising edge
                                            //    |||| |Input Bus:    0 = 12 bits// 1 = 24 bits
                                            //    |||| Dual edge:        0 = Single edge// 1 = Dual edge
                                            //    |||H-sync enable:    0 = Always low (no H-sync)// 1 = Transmitted
                                            //    ||V-sync enable:    0 = Always low (no V-sync)// 1 = Transmitted
                                            //    Reserved
    
        #define REG_09_NORMAL        0x21   //    0010 0001    
                                            //    |||| ||||
                                            //    |||| |||Monitor detect interrupt:    (MDI) 0 = Detected// 1 = Clear/Not detected
                                            //    |||| ||Hot plug detect:                (HTPLG) READ ONLY
                                            //    |||| |Receiver sense:                (RSEN) READ ONLY
                                            //    |||| Interrupt generation method:    0 = MDI generated by RSEN// 1 = HTPLG
                                            //    |MSEL output pin source selection:    (MSEL[2:0])
                                            //    |                                    000 = MSEN always high
                                            //    |                                    001 = MSEN = MDI bit
                                            //    |                                    010 = MSEN = RSEN bit
                                            //    |                                    011 = MSEN = HTPLG
                                            //    |                                    1xx = RESERVED
                                            //    VREF setting indicator:                (VLOW) READ ONLY
    
        #define REG_0A_NORMAL        0x10   //    0001 0000    
                                            //    |||| ||||
                                            //    |||| |||Reserved
                                            //    |||| General purpose inputs (same as CTL[3:1] pins)
                                            //    |||De-skewing enable:        (DKEN) 0 = Disabled// 1 = Enabled
                                            //    De-skewing setting:            (DK[3:1]) 
                                            //                                000 = 1 step     minimum setup/maximum hold
                                            //                                001 = 2 steps 
                                            //                                010 = 3 steps
                                            //                                011 = 4 steps
                                            //                                100 = 5 steps    default (recommended setting)
                                            //                                101 = 6 steps
                                            //                                110 = 7 steps 
                                            //                                111 = 8 steps    maximum setup/minumum hold
    
        #define REG_0C_NORMAL        0x89   //    1000 1001    
                                            //    |||| ||||
                                            //    |||| |||PLL Filter Enable:        0 = Disable// 1 = Enable
                                            //    |||| PLL Filter characteristic:    100 = recommended value
                                            //    |Reserved
                                            //    Sync Continuous:                0 = Disable// 1 = Enable (recommended)

------
WickyNilliams
Here's something I recently discovered I had written when revisiting some
code. Swallowing exceptions FTW :)

    
    
        try
        {
            //some code that frequently dies
        }
        catch (Exception)
        {
            // "If he dies, he dies" - Ivan Dragor
        }

------
9emE0iL18gxCqLT
"C++'s idea of a reinterpret_cast lacks sufficient cojones."
[http://code.woboq.org/qt5/qtwebkit/Source/WTF/wtf/StdLibExtr...](http://code.woboq.org/qt5/qtwebkit/Source/WTF/wtf/StdLibExtras.h.html#129)

~~~
nly
Afaik the usual practice when you want to hammer to the type system in to the
dirt is to reinterpret_cast a pointer to FROM to a pointer to TO, and then
dereference it. Alternatively just do a memcpy()

------
gutsy
I love when this shows back up (I've only been reading HN for about a year and
have seen it 3 times). Always funny to read through.

throw up //ha ha

I found that in a project I was working on for work last fall. I'm sure it
not's the same code, but it cracked me up the first time I saw it.

------
dllthomas
At a new job, I once encountered

    
    
        using namespace std; // using namespace standard

------
dbattaglia
The best I've seen recently was: // this is shit

Followed by a #region block (it's C# code): #region shit { ... }

This was done by a remote contractor on his last week on the project, which
may explain his attitude. Regardless I nearly wet myself when I saw it!

------
Jare
I did not encounter this myself and it's somewhat spoilery to post it here,
but very much worth it:

[http://www.insomniacgames.com/a-hair-tearing-out-
bug/](http://www.insomniacgames.com/a-hair-tearing-out-bug/)

------
MattGrommes
In a class on assembly in college our professor walked us through a strange
bit of real world code with the comment

# You are not expected to understand this

I've always aspired to be a good enough programmer to put something like that
in my code. :)

~~~
jgroszko
Ahhh yes, I think this is in the Lion's commentary on UNIX source book. I
remember our professor pointing out this comment and then telling us that we
are indeed expected to understand it. The code that followed I believe
implemented some behavior that made fork() work.

------
professorTuring
This is the best comment I have ever faced. Ever:

    
    
      //We have to declare it as "32 bytes long" because it is said in some magical place.
      this->diagsInfo.sbits_descr = new char*[32];

------
symisc_devel
zPtr = malloc(128);

if( zPtr == 0 ){

/*

    
    
      *If the system is so sick that we are unable
    
      * to allocate a tiny chunk of memory, there
    
      * is no much we can do here, kill this bitch
    
      */
    
      exit(-1); //Seriously?
    
    }

------
eterm
''WARNING! DO NOT REMOVE OR MODIFY THE FOLLOWING COMMENTED LINES!

With no explanation why. But then it _is_ vb6 so who knows, perhaps the
comments do make a difference. ;)

------
Aldo_MX
For me this is the best comment I have ever read.

From:
[https://code.google.com/p/xee/source/browse/XeePhotoshopLoad...](https://code.google.com/p/xee/source/browse/XeePhotoshopLoader.m#102)

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

------
careersuicide
In regards to a csv-like export of a store location database:

# This format is weird and makes no sense but it's what the client is
expecting for some reason.

------
known
[http://lxr.linux.no/+trees](http://lxr.linux.no/+trees) has many
interesting/insightful comments

------
antsam
Not really a comment but this is an exception I see that gets thrown every
once and awhile :(

throw new Exception("no exception thrown");

------
randomsearch
From the HotSpot source code:

// this infelicity should be fixed.

------
btbuildem
// debugger;

------
auggierose
Did I just get text-Rick-Roll'ed?

