Code comments as a work of art

• Introduction
• A bit of history
• Examples of comments
• Conclusion

Welcome all developers and everyone who commiserate. Everyone commented their code at least once — that's for sure. Was it your code or someone else's? Were these comments useful? Or were they made to cheer up teammates and team leads at the next code review? Let's try to discuss a bit and find answers to these questions. Try to understand the motives of people who leave comments in their program. In this article, we focus on non-standard and funny comments. We have some really cool examples for you. Let's go!

Introduction

Major research usually starts with history. The deeper in history researchers go, the better. Let's follow this tradition. But first, we'll inspect programming and code commenting.

I don't think anyone would argue that programming is art. It's almost like writing but with a bit of technology and philosophy. A modern program is, in fact, a book with instructions for a compiler or a virtual machine with a compiler. However, this code "book" is read not only by machine but also by a human. They not only look, but also edit the code, and this takes time and effort. Therefore, despite elements of creativity, a developer's work is still a routine. So, the emotional component is very important.

A human is a social being, we need communication. And it's really hard to communicate with a machine. How joyful it is to read a message to yourself with explanations or funny comments! It's even better if another developer left the message too. They probably didn't expect that you would read it. Feel the drama? Here you are, communicating. Often, you're complete strangers. But at these moments you are almost working together. You wander through the code maze and try to figure out how the code works. Leave each other hints and easter eggs. Teamwork!

Besides, you often need to blow off the steam. And if this 'steam' was caused by the code, comments allow you to blow it like this:

//Dear future me. Please forgive me.
//I can't even begin to express how sorry I am.

A bit of history

Let's return to history (preferably ancient) and, of course, writing. What can be more ancient than the word? Especially the one that was in the beginning. However, the scientists believe that in the beginning there was the cave painting. This is a caveman's subconscious desire to leave a message to their fellows or descendants. Capture life, customs, scenes of hunting or holidays. Sort of a comment to their daily (and hard) life. Yes, they did their best. But they did!

Then there were various things. The history of writing is fascinating and ambiguous. According to modern theories, writing had several centers of origins. You can read more about this in Wikipedia, for example. Anyway, humans have come a long way from simple drawings on clay tablets in Mesopotamia to modern digital methods of text generations. Including text comments in code, of course. By the way, technologies: here's a Wikipedia article about the history of computing hardware. You're welcome.

And here comes the XX century with a rapid development of technology. The first mechanical and electronic computers. Did you know that Mercedes also made arithmometers? I didn't.

Of course, the first program comments weren't that good. I'm not sure people thought about them at all. For a long time, developers used punched card for programming. Of course, they could write something funny on those cards, like: "Hey, guys, look at this cool pattern of holes". But would anybody appreciate it?

First computers were huge, complex, and were used for very serious calculations. Developers were serious too.

How could they leave funny comments? Although the gentleman in the following photo is clearly pleased with something in the printout.

Finally — the contemporary history. Computers are in every house, and programming is not a specific job. Now, the program's code is easy to create, correct, and comment.

The main thing is to use this opportunity wisely. Because there's nothing worse than a map that doesn't match the terrain, or a comment that doesn't match the code:

/**
 * Always returns true.
*/
public boolean isAvailable() {
    return false;
}

But how often do developers leave comments, especially funny ones? There are no exact statistics. For the sake of interest, I calculated the comments' percentage (of the total number of lines) in our analyzer. Here are the statistics by every programming language:

• C++: about 1 082 000 lines, 15% comments;
• C#: about 509 000 lines, 6% comments;
• Java: about 80 000 lines, 16% comments.

I don't know what conclusions can be drawn here. Does that mean that the C# developers are lazier than the C++ ones, and therefore they rarely comment the code? :) Or is their code so cool and readable that they don't need to comment anything? I looked at some comments, and they are all quite serious. Except that in many places I saw the classic "Don't touch!!!". I'm glad to see that nothing human is alien to our developers.

Examples of comments

Well, how are things with funny comments from other developers? You can find a lot of examples on the Internet. I found an old but popular question on Stack Overflow: "What is the best comment in source code you have ever encountered?". It has 518 answers. I've already used a couple of them in this article.

At first, I wanted to rate the most epic comments here. But after I looked through the low-rated answers, I realized they were quite funny too. That's why in this article I'll show you the answers I like the most. This is not a rating; the list is arbitrary.

Some of the responses left by the Stack Overflow users are very emotional and even contain strong language. In such cases, I'll only give a link to the comment instead of pasting the text. But links often contain really funny things. Here's an example. Also, almost every answer contains a discussion between users — you can follow the links to read the threads.

Poetry

Let's start with the most popular answer — 1460 votes. It has two comments. The first one is called code poetry. Below is the full text:

/**
* For the brave souls who get this far: You are the chosen ones,
* the valiant knights of programming who toil away, without rest,
* fixing our most awful code. To you, true saviors, kings of men,
* I say this: never gonna give you up, never gonna let you down,
* never gonna run around and desert you. Never gonna make you cry,
* never gonna say goodbye. Never gonna tell a lie and hurt you.
*/

A great example of how to bring a powerful emotional component to a soulless code. Of course, you should not get carried away with such messages on a regular basis. But I am sure — such a comment, when met, will cause only positive emotions.

Interactive

The second comment from the same answer adds a bit of interactivity and turns work into a game:

// 
// Dear maintainer:
// 
// Once you are done trying to 'optimize' this routine,
// and have realized what a terrible mistake that was,
// please increment the following counter as a warning
// to the next guy:
// 
// total_hours_wasted_here = 42
//

The author wrote that they didn't publish the code with this counter. But even if it's made for themselves, it's a great example of a comment that encourages communication.

Code magic

"I don't know how, but it works". I think every developer left something like this in their code at least once. I did. One of the examples of such classics:

//When I wrote this, only God and I understood what I was doing
//Now, God only knows

Similar comments are found in other answers, for example:

// Magic. Do not touch.

And another one:

// I put on my robe and wizard hat...

By the way, I copied my "magic" code from somewhere, but I never figured out how it works. :)

The Unknown

Developers often overestimate the complexity of their code. As a result, we get the following: comments:

/* You are not meant to understand this */

Perhaps the author didn't understand anything either. Another example:

/**
 * If you don't understand this code, you should be flipping
 * burgers instead.
*/

Well, we've got to look at the code first. Finally, a Dante reference never hurts:

//Abandon all hope ye who enter beyond this point

The ninth circle.

Don't you dare!

The answers have interesting comments that strictly prohibit code editing or warn about the negative consequences of this action. Example:

// Autogenerated, do not edit. All changes will be undone.

This comment is slightly too exquisite to leave in normal (not autogenerated) code, don't you think? And here's a more detailed explanation why you should decide against editing:

/*
 * You may think you know what the following code does.
 * But you dont. Trust me.
 * Fiddle with it, and youll spend many a sleepless
 * night cursing the moment you thought youd be clever
 * enough to "optimize" the code below.
 * Now close this file and go play with something else.
 */

Here's another comment that prohibits deleting of a comment:

// If this comment is removed the program will blow up

Another unequivocal warning:

// I know the line below is wrong, but it came that way from our IP
// vendor, and the driver won't work if you "fix" it. I've had to
// revert this change 4 times now. Leave it alone, or 
// I will hunt you down and hurt you

And the last one in this block:

// (c) 2000 Applied Magic, Inc.
// Unauthorized use punishable by torture, mutilation, and
// vivisection.

If it ain't broke, don't fix it.

Digital loneliness

In the beginning of this article, I wrote about the lack of communication and emotional hunger among developers. Well, here's the proof:

// sometimes I believe compiler ignores all my comments

And another one:

//Mr. Compiler, please do not read this.

Here's a plea, but to whom or what?

/* Please work */

Yes, that's who the programmers are — inventive, with a great sense of humor. However, sometimes they feel lonely and try to talk to the machine.

Grumpy comments

Yes, generation gap is no joke. Here's a bit of old man's grumbling:

* ...and don't just declare it volatile and think you've solved
* the problem. You young punks think you know what volatile
* means... why in my day we had to cast it volatile uphill
* both ways, and the code still didn't work! Whippersnappers...

Yes, everything was better these days.

I'll do it tomorrow

Procrastination is a scourge of our times. Of course, developers couldn't avoid that too. An example of a peculiar TODO note in code:

// drunk, fix later

I don't support this behavior in any way. But we're all humans, after all.

Here's another TODO comment, but here something went wrong:

// TODO: Fix this.  Fix what?

A good reason to talk. If it is not clear what to write in the comments, use this:

// TODO make this work

If you don't want to write a long comment:

// THE LOOP THAT DO EVERYTHING!!!!!!!

If there's no time to comment now, here's an option:

-- Comment this later

I'd rather get some sleep.

Make it clear

How could we miss Captain Obvious-style comments? Here's one:

return 1; # returns 1

Another example:

i++; // increment variable i

Yes, it is clearly impossible to understand anything here without explanations. Thanks, Cap.

Funny code

I met several examples of interesting constructions — a combination of keywords of programming languages, variable names and commentaries. It looks really fun. Here's one of such comments:

long john; // silver

Another example:

long long ago; /* in a galaxy far far away */

Here's a very interesting comment:

double penetration; // ouch

Judging by the comment, the author also thinks that the construction is ambiguous. Another spicy comment, since we mentioned it:

virgin = 0;     /* you're not a virgin anymore, sweety */

Well, the minus would have been sadder.

Not guilty!

There's a story behind many of these comments. For example, in the following comment. That's why I advise you to follow the link and read the whole story. Here is a version of the classic disclaimer:

// I am not responsible of this code.
// They made me write it, against my will.

Another disclaimer (and an easter egg for another developer):

/*
This isn't the right way to deal with this, but today is my last
day, Ron just spilled coffee on my desk, and I'm hungry, so this
will have to do...
*/

return 12; // 12 is my lucky number

I like 42. There was also a comment with a partial admission of guilt:

// If this code works, it was written by Paul DiLascia. If not,
// I don't know who wrote it

You're a sly one, Paul. As I said, programming is a hard work.

// This is crap code but it's 3 a.m. and I need to get this working.

No one will distract you at night, though.

Coffee time

How about some culinary humor?

} catch (PartInitException pie) {
    // Mmm... pie

And, of course, coffee:

// need a coffee to fix this.

Why is celery wilted? Follow the link to get the answer:

// Wilted celery?

We are for a healthy lifestyle.

Not mine — not sorry

Comment on someone else's code? Easy! I met examples from quite harmless:

// This only exists because Scott doesn't know how to use const
// correctly

to the most emotional. That's when I will only share a link. Careful, there's a lot of pain. What's interesting — the code and the comment weren't published by the author. They accidentally found this answer on Stack Overflow and decided to give explanations.

Developers also emotionally comment their own code. Especially if it's Quake III and there's some hardcore coding. Again, I'll only give a link.

When you're Carmack.

Sometimes text is not enough

Then the good old pseudo-graphics come to the rescue and show the whole range of feelings. We can't just ignore it:

## Safety pig has arrived!
##                               _
##  _._ _..._ .-',     _.._(`))
## '-. `     '  /-._.-'    ',/
##    )         \            '.
##   / _    _    |             \
##  |  a    a    /              |
##  \   .-.                     ;  
##   '-('' ).-'       ,'       ;
##      '-;           |      .'
##         \           \    /
##         | 7  .__  _.-\   \
##         | |  |  ``/  /`  /
##        /,_|  |   /,_/   /
##           /,_/      '`-'
##

And a couple of equally creative comments. Here's a link and a link because I'm not sure that If I copy and paste the text, everything will stay the same.

And they're surprised that the source code is large.

Worth more than a thousand words

It's cool when developers leave short comments. But here they overdid it a little:

// HERE

After commenting it's time to rest:

// zzzzZZZZzzzz....

And maybe practice philosophy:

# let's pretend we are free, for a while

Save energy to coding.

Scary (or not)

I found a comment with a bit of cyber-mystics:

// This will save us ~0.5 sec for every user and please the machine spirits.

Mixed feelings: scary, but interesting:

// Choose! Choose the form of the Destructor!
// The choice is made! The Traveler has come!

Whatever, just don't summon the disassembler.

Other

A couple of comments that don't belong to any category.

Release history by developer. Closed private version:

//3.4  JeK  My manager promised me a lap dance if I can fix this
//          release
//3.5  JeK  Still waiting for that dance from my manager
//3.6  JeK  My manager got changed, the new manager is hairy, dont
//          want the dance anymore
//3.7  Jek  Got that dance, yuck!

Well, they got the present, after all.

Usually, comments are inseparable from the code. But there are exceptions:

// This comment is self explanatory.

For all occasions. I checked.

Here someone didn't have enough comments. And they made it clear:

//Please comment on your source code

When your whole life is just comments.

Legal support never hurts:

/* My lawyer told me not to reveal */

Fired!

Conclusion

Finally, I want to show you two comments that conatin all the wisdom and philosophy of programming. First:

'NO COMMENT

And second:

// nobody read comments!

That's all. I think it's clear that code comments are infinite. You can find a million more funny and not funny examples. Comment your code, comment someone else's, don't keep it to yourself. Make it fun. And of course, remember to correct grammatical errors in comments on the release day! (it's an old joke)

Thank you for your time.

// good luck!