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.


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

OJ said...

This is one that I discovered in our codebase recently:

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

class Vector
// ...

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


ayumi said...

wonderful work! the way you discuss the subject i'm very impressed. i'll bookmark this webpage and be back more often to see more updates from you.


Lee Shin said...

spot on with this write-up, i like the way you discuss the things. i'm impressed, i must say. i'll probably be back again to read more. thanks for sharing this with us.

Lee Shin

Aissa said...

Nice post. Thank you for taking the time to publish this information very informative; so happy to be given a privilege to post a comment here.


sarah lee said...

I really enjoyed reading your article. I found this as an informative and interesting post, so i think it is very useful and knowledgeable. I would like to thank you for the effort you have made in writing this article.

Cindy Dy said...

It is great to have the opportunity to read a good quality article with useful information on topics that plenty are interested on.


andrea chiu said...

I understand that every person has the passion in any aspects or things. If you love something and it came in front of you it completes your day and your mood turns into something you won't expected. I love your work and I want to read more about it. Visit my site if you have time . Thank you.

andrea chiu said...

Thanks for sharing your article and for giving us the chance to read it. It is very helpful and encouraging. Visit my site too.

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