Sunday, September 9, 2007

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.

6 comments:

Mike Venneman said...

Here are my two favorites:

The first could spark a new category: The Oxymoronic. I think this programmer was just trying to be funny.

// No comment

The second actually seemed to stop time after I read it because it was so unbelievable.

// This is something [coworker's name]
// told me to do, but I am not sure why.

I mean really... Did the person pass away after leaving that vague nugget of information? Wouldn't it have been better to have a quick conversation with him/her before writing this comment?

Michael Easter said...

Excellent examples, Mike...

Someone else wrote to me and reminded me of this classic:

// This is only a temporary kludge

Naturally, those comments (and the kludges) can stick around for years...

Anonymous said...

This is one that I discovered in our codebase recently:

// This class is responsible for handling
// date the time formats.

class Vector
{
// ...

Anonymous said...

Funny comments in code can brighten a developer's day, as long as the code they're asked to fix later on isn't littered with them.

Facebook's recent code leak has some amusing comments. It's probably better that I don't post a link here though...

generic viagra online said...

Thanks a lot for sharing this nice article.







......Alex

Jamu Kuat said...

there was a new record could be better. If it could be that there is humor . laugh will further beautify the atmosphere while reading . such or maybe the other, I really hope you soon launch your new posts , about whatever it ...... would have been very helpful for me ,Obat Ejakulasi Dini .... thanks for giving a lot of new experience for me !

very nice food to be felt and I am keen to make and try it , I hope you are sensitive to provide information about how to make a banana cake , because I wanted to make it quickly , help me want to do it and I would go back to see what you post . I want to have Obat Hernia haid di apotik natural and safe for me to use , I hope you can help to give me a banana cake recipe