Crazy Code Comments: Adventures in the Margin

Some colleagues and I were recently talking about Fermat's Last Theorem and how an innocuous comment in the margin, "I have a truly marvelous proof of this proposition which this margin is too narrow to contain", sparked a chase for the proof that lasted centuries. This book is a delightful, mainstream work on the proof and the history of the theorem.

The conversation led me to think about our margins as developers: comments. It's quite a tangent but surely these are the modern-day margins: the untamed jungle of writing where not even the mighty compiler can pass judgement.

What are some of the craziest things you've seen in the comments? Here are some select themes from my experience.

Fermat Wanna-bes

Whenever I see a code-comment that uses the word 'obviously', then it is either a silly, needless comment or they are following in Fermat's footsteps. Something to the effect:


// Obviously, we need to serialize the data and convert to
// Latin-2 and then one's complement for reasons that are
// perfectly clear and need not be specified.


Pseudo Source Control

I'm probably guilty of this one: checking in code with an older implementation contained in the comments. Code subjected to this treatment does not age very well. Ugh.

Flame Wars

A favourite:

• Person A has a comment explaining a code segment.
• Person B writes an editorial comment on the approach, and leaves in the original comment.
• Person C (or better: Person A) retorts with a defense of the original code!
  
• The chaotic fun continues with a flame war, replete with threads, right in the code.
  

If You're Reading This, It Must Suck To Be You

I've seen comments to the effect:

// The hyper-flyweight-quantum-double-dispatch pattern was
// attempted here but later it was discovered it wasn't a good fit.

Yikes... That's never good but at least they get kudos for intellectual honesty.

Small World

It's always interesting to read a comment with a name of someone you once worked with, or know in your city. Bonus: comments that you wrote in a previous life.

Equine Esoterica

In my undergrad studies, we used a textbook that cited this infamous comment as a bad example:

// horse string length into correctitude

Oh, I love that line. For that class, I ensured that all of my programming assignments had that in there somewhere.

The Best Yet

I never thought I would see anything to beat the last one, but this did it. This is a real example from the wild:

// .... . .-.. .-.. ---  .-- --- .-. .-.. -..
// begin section
// .... . .-.. .-.. ---  .-- --- .-. .-.. -..

If you look closely, the bookmarked lines are in fact Morse Code. Brilliant... absolutely brilliant. (I'll let you figure it out. See this post for a hint)

Fermat would have been proud.