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

  /* =========================================
               THE BOUNDARY OF SANITY
                 Behold, stranger!
   ========================================= */

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

#6

Post by yakubin » Fri, Oct 08, 2021, 1:00 PM UTC

Joe Armstrong in his talk "The Mess We're In"[1]:

> Robert Virding, who developed Erlang with me, was famed for his comment... I think he only... Singular... The entire stuff he wrote had one comment. In the middle of a pattern-matching compiler was a single line that said "And now for the tricky bit"

[1]: https://youtu.be/lKXe3HUG2l4?t=645>

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

#7

Post by atatatat » Fri, Oct 08, 2021, 1:26 PM UTC

rasz wrote: post #3

Linux driver >"Do not purchase this card, even as a joke." https://elixir.bootlin.com/linux/v3.1/source/drivers/net/3c5...

The follow-on improvement comments, and the quick DOC section are pretty hilarious, as well.

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

#8

Post by revolvingocelot » Fri, Oct 08, 2021, 1:57 PM UTC

I didn't organically encounter it [0], but my favourite is probably

   * You are not expected to understand this.

I find the ultimately misplaced confidence [1] of the comment quietly inspiring, in the context of who wrote it. Even the titans of yesteryear fallaciously convince themselves that, hey, the code works fine, let's get going, and consequently have to bash their heads against some weird quirk they're unintentionally exploiting (and then just rewrite the whole thing).

[0] http://catb.org/~esr/jargon/html/Y/You-are-not-expected-to-u...

[1] https://archive.is/eeYMW [2] https://en.wikipedia.org/wiki/Lions%27_Commentary_on_UNIX_6t...

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

#9

Post by [deleted] » Fri, Oct 08, 2021, 2:45 PM UTC

atatatat wrote: post #7

rasz wrote: post #3

Linux driver >"Do not purchase this card, even as a joke." https://elixir.bootlin.com/linux/v3.1/source/drivers/net/3c5...

The follow-on improvement comments, and the quick DOC section are pretty hilarious, as well.

[deleted]

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

#10

Post by [deleted] » Fri, Oct 08, 2021, 2:46 PM UTC

atatatat wrote: post #7

rasz wrote: post #3

Linux driver >"Do not purchase this card, even as a joke." https://elixir.bootlin.com/linux/v3.1/source/drivers/net/3c5...

The follow-on improvement comments, and the quick DOC section are pretty hilarious, as well.

[deleted]