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

http://stackoverflow.com/questions/184618/what-is-the-best-comment-in-source-code-you-have-ever-encountered

by yammesicka • 13 years ago

157 95 13 years ago

stackoverflow.com

ananth99• 13 years ago

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

LOL.

jgrahamc2• 13 years ago

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

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

eitally• 13 years ago

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.

jgrahamc2• 13 years ago

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

dspillett• 13 years ago

as it was at the time of development

Also as it was interpreted at the time of development - the two should be the same of course but we don't live in a perfect world. If a comment explains exactly what the code is trying to do and why, and the "what" matches the code but doesn't match the client expectations then as well as fixing the code you know you might need to update documentation elsewhere too to make it cleare.

_pmf_• 13 years ago

Superb. (TODO: look for an ASCII drawing mode for Eclipse)

Fishkins• 13 years ago

IDK about Eclipse, but Emacs comes with M-x artist-mode

moron4hire3• 13 years ago

DrRacket lets you embed images directly in source code.

anonymous• 13 years ago

Reminds me of the comment at the start of python's heapq module: http://hg.python.org/cpython/file/bd8afb90ebf2/Lib/heapq.py . Grammatically not a comment, but I would count it as one semantically.

jcampbell1• 13 years ago

I really hate how heapq in python doesn't allow a comparator function. Stuffing tuples is the accepted solution, but it feels wrong and adds a bunch of unnecessary code when using heapq. Nice comment, but sub-par implementation.

harrytuttle• 13 years ago

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.

adnam• 13 years ago

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

[edit] Yep.

idProQuo• 13 years ago

It's the kind of thread that really has no home. Proggit would shoot it down for being frivolous, HN would probably do the same if it was a self-post.

I'm glad that StackOverflow leaves closed questions visible. A lot of the value I get from SO comes from opinion-y questions getting answered by experts.

maaaats2• 13 years ago

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• 13 years ago

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

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

m0nty• 13 years ago

Yes, but this is fair comment and nicely put:

question is now closed, I think 528 "answers" is probably enough, no? :) – Jeff Atwood

It is annoying, though, how so many useful SO questions get closed for various reasons when they are just the question I want answered. Perhaps the real problem is Google giving a lot of weight to SO answers, even when they are closed?

sixothree• 13 years ago

I once posted a question citing reason I thought it was not duplicate even citing each of the few similar 'duplicate' questions I could find which did not answer my specific question.

Of course it was closed immediately.

bmm6o• 13 years ago

Yes, and deservedly so. It's not a question with an answer, it's not even a poll. Other communities would close it as "Chatfilter" or "GTKY". What's interesting is that it was ever allowed on SO, and that it stood as acceptable for so long. And I wonder if the fact that there was a time in SO's lifecycle where it was accepted was important to the site's success. It's the sort of question that fosters community and good will in a way that "MVC 4 Validation using Data Annotations and Jquery" does not.

ColinWright• 13 years ago

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=604463

https://news.ycombinator.com/item?id=620595

https://news.ycombinator.com/item?id=1626686

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

https://news.ycombinator.com/item?id=1805021

https://news.ycombinator.com/item?id=2566782

https://news.ycombinator.com/item?id=2791385

https://news.ycombinator.com/item?id=4838161

https://news.ycombinator.com/item?id=5140016

https://news.ycombinator.com/item?id=5379948

https://news.ycombinator.com/item?id=5978923

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

kbenson• 13 years ago

https://news.ycombinator.com/item?id=2566782 is so meta.

andyjohnson0• 13 years ago

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

rheide• 13 years ago

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_• 13 years ago

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• 13 years ago

Vets? Doctors?

What does a programmer have to cry about?

dbattaglia• 13 years ago

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!

peterkelly• 13 years ago

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

- Donald Knuth

gprasanth• 13 years ago

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

spatulon• 13 years ago

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.'".

9emE0iL18gxCqLT• 13 years ago

"C++'s idea of a reinterpret_cast lacks sufficient cojones." http://code.woboq.org/qt5/qtwebkit/Source/WTF/wtf/StdLibExtr...

qznc• 13 years ago

Relying on undefined behavior surely shows sufficient cojones.

nly• 13 years ago

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()

dmoney• 13 years ago

  // Maybe these two lines will crush everything.

Whatever it referred to was no longer there.

Jare• 13 years ago

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/

ja27• 13 years ago

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.

sturadnidge• 13 years ago

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.

WickyNilliams• 13 years ago

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
    }

eterm• 13 years ago

''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. ;)

fennecfoxen• 13 years ago

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

auvi• 13 years ago

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• 13 years ago

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

sanswork2• 13 years ago

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• 13 years ago

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

sanswork2• 13 years ago

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.

auggierose• 13 years ago

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

wrl• 13 years ago

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

    free(self); /* so liberating */

__david__• 13 years ago

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

groovy2shoes• 13 years ago

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

sigil• 13 years ago

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);

gutsy• 13 years ago

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• 13 years ago

At a new job, I once encountered

    using namespace std; // using namespace standard

6d0debc0712• 13 years ago

/* 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• 13 years ago

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

6d0debc0712• 13 years ago

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

_halgari• 13 years ago

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!"

ScottBurson• 13 years ago

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

joshuahedlund• 13 years ago

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.

MattGrommes• 13 years ago

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• 13 years ago

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• 13 years ago

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];

pilif• 13 years ago

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.

robomartin4• 13 years ago

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.

srl• 13 years ago

Back when I was first learning C++.

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

randomsearch• 13 years ago

From the HotSpot source code:

// this infelicity should be fixed.

helloTree• 13 years ago

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

$ man xorg.conf

and search for "nobody"

;)

jpitz• 13 years ago

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

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

slowmover• 13 years ago

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

careersuicide• 13 years ago

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.

robomartin4• 13 years ago

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• 13 years ago

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

robomartin4• 13 years ago

code should be self-documenting

Which is a myth. Try to come back to code five years and three languages later and see how self-documenting it is. It isn't.

I could maybe --possibly-- stretch disbelief and accept that if someone works with one language and one platform for a long time the code will be self documenting to that person or that team. This is not the case for multi-technology projects with generations of people touching the code base.

I'll give you a very concrete example. About fifteen years ago we spent three months authoring a tool in Visual Basic for Applications (VBA). This tool was used to automate certain aspects of the EDA (electronics design software) tool we were using at the time. The custom software was needed in order to vastly improve productivity with 1,000+ pin chips. The VBA tool effectively linked Excel with PCAD and reduced a twelve hour task to less than an hour.

Well, I have not touched VBA in probably fifteen years. The code is full of comments about the very things I described in my prior post: intent, design, thoughts, ideas, enhancements, problems, etc. After fifteen years of not touching the language or the application I can jump into that code base and be up and running within not much more than an hour.

It is hard to place a number on the value this adds to a project. It is nothing less than huge when it comes to supporting, maintaining, migrating and enhancing it.

"x+=5; //add 5 to x"

Clearly the domain of morons.

iloveponies• 13 years ago

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.

crpatino• 13 years ago

What you describe about the development process, ... , is important but doesn't really belong in the source code.

Except that in really big/successful projects, the proper places are outdated specs that end up buried in obscure unindexed archives. This can happen for a lot of reasons, technical debt, intellectual property acquisition, erosion of institutional knowledge due to personnel attrition, etc.

On the other hand, source code is forever. It is the thing that you cannot unknowingly get rid off without getting rid of (your ability to update) the product itself.

Da Vinci didn't write on the back side of the Mona Lisa the production process for his paints.

If you were a curator of the Louvre Museum, your job would have been easier if he did.

davidcuddeback2• 13 years ago

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.

I used to believe that too, but I now believe that that point-of-view only addresses the accidental complexities of reading code. Don't get me wrong, descriptive function and variable names are great and make understanding code much easier. But I think it misses the forest (program structure) for the trees (functions).

Where I get off that train is when trying to understand a program's structure. How do the modules decompose the problem being solved? Why was it designed a certain way? There's usually a combination of technical and domain knowledge that influenced the design. Sometimes, there's a philosophy that needs to be shared by the whole team to work effectively. I need to know all of that in order to effectively extend the program.

There are also times (though less common) that I believe comments are needed to understand even the most clearly-written functions. This is usually when one needs background knowledge to understand the function. For example, a mathematical derivation isn't obvious when you're staring at a line of trig functions. At the very least, code like that needs a reference to a Wikipedia article or a book.

davidcuddeback2• 13 years ago

It almost seems that there's a generation of programmers being taught that comments are a waste of time.

That might be true. I had at least one professor who discouraged comments. He said, "I know how to read code." I can understand that in his particular case, he didn't need documentation for higher-level understanding. He taught us the algorithms and data structures being used and he gave us a boiler plate design that we had to conform to. All we had to do was fill in the function bodies and write a main() function.

Unfortunately, it's possible that some students might have adopted that as an overall attitude without recognizing that the context in which it was said invalidated the need for comments for any higher-level understanding. A lot of students looked up to this professor.

That's just a single example. I have no idea how common this is.

peter303• 13 years ago

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• 13 years ago

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;

robomartin4• 13 years ago

    #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)

pkulak• 13 years ago

I've come across this one several times courtesy of https://news.ycombinator.com/user?id=aphyr

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

techtalsky• 13 years ago

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

VikingCoder• 13 years ago

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

known• 13 years ago

http://lxr.linux.no/+trees has many interesting/insightful comments

btbuildem• 13 years ago

// debugger;

habosa• 13 years ago

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• 13 years ago

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.

belorn• 13 years ago

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.

mtm• 13 years ago

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.

Aldo_MX• 13 years ago

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

From: https://code.google.com/p/xee/source/browse/XeePhotoshopLoad...

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

symisc_devel• 13 years ago

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?

}

agrona• 13 years ago

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

antsam• 13 years ago

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

throw new Exception("no exception thrown");

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

Related Stories