Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

Is a small amount of lighthearted wording or humor acceptable in source code documentation?

For example, I have an algorithm that has a message hop around a graph (network) until its path forms a cycle. When this happens it is removed from the queue of the node it last resided on which removes it from memory. I write that in a comment, and finish the comment with "Rest in peace, little guy".

That serves very little documenting purpose, but it cheers me up a bit, and I imagine it might cheer up other people I'm working with as they read through the code.

Is this an acceptable practice, or should my in-code documentation resemble as much as possible the speeches of 2004 United States presidential candidate John Kerry? ;-)

share|improve this question
17  
Humor is off topic –  Crazy Eddie Jun 30 '11 at 7:04
74  
That didn't cheer me up at all. Actually, it made me kind of depressed. I'm going to go mourn for the message. –  Maxpm Jun 30 '11 at 8:00
15  
@Crazy Eddie You really ARE CRAZY, Eddie –  Wildling Jun 30 '11 at 8:55
2  
@Tyler K. Looking for this? stackoverflow.com/questions/184618/… –  NickAldwin Jun 30 '11 at 18:19
33  
JavaDoc is a joke, does that count? –  Reuben Mallaby Jun 30 '11 at 21:45
show 15 more comments

29 Answers 29

up vote 225 down vote accepted
  1. Thou shalt not sacrifice legibility of code, nor shall you give variables or methods "funny names".
  2. Thy humor shall not be offensive to minorities nor require censorship, for thy source code may ever be laid bare and judged.
  3. Thy documentation must make perfect sense even with all humor deleted.
  4. Thy humor should be identifiable and not mistaken for documentation, even if it is obscure and no other shall "get it".
  5. Guard thy humor from customers and end-users, unless you possess the backing of thy bosses, for either may be mirthless and quick to anger.
  6. Avoid the pop-culture references of mammon, for they grow stale with time.
share|improve this answer
7  
Commenters: comments are meant for seeking clarification, not for extended discussion. If you have a solution, leave an answer. If your solution is already posted, please upvote it. If you'd like to discuss this question with others, please use chat. See the FAQ for more information. –  user8 Jul 1 '11 at 19:27
2  
Regarding #2: What if the humor is offensive to majorities? Would that be acceptable, if only from a minorities point of view? What if the minorities are not offended contrary to expectations by the majority? Do minorities have the right to defy the expectations of majorities? –  ThomasX Mar 5 '12 at 15:25
show 2 more comments

I would say it's not only OK, I would strongly encourage it. Most docs are so dry you can die of thirst just reading them. A little humor sprinkled here and there makes the whole thing more palatable.

share|improve this answer
13  
Some people are of the opinion that if some business person sees it and doesn't get the humor then they will think less of you. Fair enough, but to be honest I'm confident that I would rather work with someone who has a sense of humor, so I see it as a win win. –  Jeff Welling Jun 30 '11 at 2:02
5  
@Jeff: Well, to quote from some of my own docs in CDB: ... int iJoke; /* if iJoke == iJokeNil, then f*ck'em if they can't take a Joke */ –  Peter Rowell Jun 30 '11 at 3:13
4  
+1 So long as it doesn't in any way detract from clarity and isn't offensive, a bit of humour is a good thing. –  Jon Hopkins Jun 30 '11 at 9:06
5  
Many years ago a colleague wrote a complete COBOL subroutine using naughty words for variables. As in PERFORM INTERCOURSE VARYING HIPMOVEMENTS FROM SLOW TO FAST UNTIL PARTNER.... and so on –  mplungjan Jun 30 '11 at 17:18
show 2 more comments

In professional projects probably not

My issue with humour in code is that if your code has bugs, or is not brilliantly written all I'm going to be thinking as I read it is "I wish the person writing this had spent a little less time being funny and a bit more time concentrating on the code".

However, if in a test for a string function you do some cute manipulation of the string that is kind of funny or interesting, then I think that's a bonus.

Software, like all technical things is dry and technical. If you rebel against that you are only making life harder for yourself.

As you write your jokes ask yourself this "If I mess up and my boss catches this on his worst day am I going to be happy sitting next to him as he goes though my code and reads my humours one liners?"

share|improve this answer
19  
+1 for the boss check. That is a pretty good criterion. –  glenatron Jun 30 '11 at 9:56
5  
"I wish the person writing this had spent a little less time being funny and a bit more time concentration on the code". Boy is that true. –  HLGEM Jun 30 '11 at 19:55
2  
Or maybe you just don't want to work for a boss that would get upset for something like that... –  Radu Murzea Nov 22 '13 at 13:03
add comment

From Real World Haskell:

How well does this function work? For positive integers, it's perfectly cromulent.

first comment:

It is a little known fact that, just like the programming language Python requires you to be familiar with a few stock Monty Python phrases, Haskell requires you to brush up your knowledge of The Simpsons

I think this proves that it's perfectly acceptable to make Monty Python jokes in Python comments, and to make Simpsons jokes in Haskell comments. (Though I must admit to making a Monty Python joke in a Java comment once.)

Perhaps programmers.SE can come up with a more complete programming language <-> comedy show mapping?

share|improve this answer
3  
Cromulent is a perfectly cromulent neologism; in a few years, expect it to be in the OED. –  Richard Morgan Jun 30 '11 at 13:05
3  
A noble heart embiggens the smallest man. –  Jesse C. Slicer Jun 30 '11 at 17:48
show 1 more comment

I think humor in technical documentation and code comments is fine! And I, too, would encourage it.

Humorous code comments are certainly much better than most of the "comments" I see, which are where somebody's turned off code with no explanation, and then put it into production, and some poor slob (like me) has to figure out why.

One of the funniest things I ever saw along that line was an error emitted by Apple's MPW C compiler. It flagged "Error blah-de-blah on line 73: ..." and then proceeded to quote the entire relevant section of the ANSI spec, and if you scrolled over all thousand-ish characters to the right, you saw, "(not that you really care.)"


Added 30 June 2011...

The key to success here, as the OP said, is "lighthearted wording or humor". Because you don't know who's going to see what you write, it's a very bad idea to write things that can be construed as mocking or negatively criticizing anybody or anything: the code, the previous people who worked on the code, the users of the code, or much of anyone else.

Always keep code comments etc. light, positive, and non-personal - no matter how big a pile of dung you really think the last programmer left you to work on. Even if he quit the company years ago, they may hire him back as your boss. I've seen stranger things happen... :-)

share|improve this answer
5  
@Bob Murphy: a classic in C++ error: ‘long long long’ is too long for GCC (but long long is not, of course) –  Matthieu M. Jul 3 '11 at 19:39
3  
@Matthieu long long ago; // in a galaxy far far away –  rightfold Aug 3 '11 at 3:45
show 2 more comments

It's fine if it's really funny. Otherwise it's just annoying. In other words:

My jokes are fine, but yours are not. :-)

share|improve this answer
3  
+1 for "my jokes are fine, but your are not." Good point, actually. –  Jannis Jul 1 '11 at 12:50
1  
So that's what git branches are for... –  naught101 Jun 7 '12 at 6:42
add comment

Once, while hacking around an IE bug, I wrote the comment: "This is the worst hack I have ever written. May God have mercy on my soul."

I wanted the following devs to know that the code was not random or useless and that I didn't want it that way, but I had no choice.

Years later, someone found that comment and the whole team had a good laugh. It came up a few times after that, too.

So yes, I think funny comments can be very good for documentation, provided that they are on-topic and not offensive.

share|improve this answer
7  
Careful with that. Now you cannot write worse hacks or the comment is wrong! –  user1249 Jul 3 '11 at 6:56
show 1 more comment

I advise against it. Humor translates very poorly and can cause more confusion than it is worth, especially when lawyers get involved. You'll never know when something you think is a joke are instead fighting words in some other culture.

An example of the time wasted with one cute remark was mentioned in Code Complete (among many other places:

MOV AX, 723h ; RIPLVB

Alternative variation of the story by Yourdon (which is probably more "accurate" because it is in octal, not hex). And this is the closest I can come to green bar paper with the style-sheet for this site.

The "humor" in that constant is that when converted to decimal, it is the year that Beethoven died, so rest in peace, Ludvig Van Beethoven!

share|improve this answer
1  
@Kristian's joke comment is not helpful. Document WHY the loop is removed. Some developers may well be sick and tired of jokey , unhelpful comments. –  Tim Williscroft Jun 30 '11 at 4:43
show 1 more comment

When I found small jokes in documentation and code comments it's make me feel happy. Do it. No matter what your boss can say. It's our priviledge as developers (but don't abuse of it).

share|improve this answer
add comment

Who in the world looks back on a job and regretfully thinks to themselves

"Man, I had way too much fun there."

share|improve this answer
3  
The one who got fired for not focusing on his job, maybe? –  Zano Jul 1 '11 at 0:24
show 2 more comments

My sense of humour may be lacking, but experience has taught me to regard clever comments as a code smell (*):

  1. When I see a clever comment, it is often encountered by overly clever code.
  2. If the coder likes his joke and it is tightly bound with the code itself, he will often be reluctant to refactor the code if it means losing the joke.

*: Remember that the definition of a code smell is not code that is wrong, but just something that experience has taught us often is accompanied by bad code. Your code may be completely correct, but if it "smells", I will spend some extra time when reviewing your code.

share|improve this answer
4  
On point 2 - tight coupling is always a code smell; it should be possible to refactor the joke so it is usable separately from the code. –  Tom Anderson Jul 3 '11 at 18:23
add comment

I once came across this in a project that didn't exactly have stellar documentation:

Documentation is like sex: When it's good, it's REALLY good and when it's bad... well, it's still better than nothing.

share|improve this answer
add comment

Like all communication it depends on your audience.

Will someone reading a cutesy comment you've made get annoyed and perhaps think less of you for writing something so silly? Is this customer facing code? Do you find yourself writing comments that belong on the Daily WTF as a gag or over the top in-joke? If so, you might want to reconsider.

Is the joke easy to get and does it actually add value and meaning to your code? If so, then I say go for it. A sense of humor is a a great thing to have!

share|improve this answer
add comment

On internal documentation it's no problem for me but it depends 100% on your company's culture. I appreciate the odd joke in the code or documentation, as long as it's harmless fun and not offensive.

share|improve this answer
add comment

Humour has been proven to help people relax and improve their understanding when reading

Use your common sense though man - who's going to be reading the documentation?

If it will bring a smile to the reader's face without sullying your reputation, go for it - just don't let it get in the way of your work

share|improve this answer
add comment

It's not okay.

Obviously, it depends on the situation. If it's your pet open source project, you know the audience is more light hearted, and the project is completely within your sphere of influence, free $country, go ahead and do it, for varying values of $country.

But if you're the kind of person that has to ask... Or this is a work project or the documentation will be read by more buttoned up folks or possibly paying costumers... Then don't do it.

Would your boss be okay with you doing it?

Edit: To clarify, I'm not saying documentation should be void of humor. Personally, I think lots of things in life could benefit from an injection of humor. But it always depends on the situation.

share|improve this answer
show 2 more comments

There are few problems with humor in code:

  • many jokes are based on words play, which might be incomprehensible for non-native speakers;
  • many jokes reference something local, which won't be understood even by native-speakers, which happen to live in other country;
  • many jokes reference current events, celebrities or memes, code may outlive their fame;
  • some jokes which may seem innocent to you, might be perceived as offensive somewhere else;
share|improve this answer
add comment

I like random humor that's totally unexpected. For the opposite of what I mean, see the Head First borks.

Also, a good joke can be really mnemonic. For instance, I won't try to regex-parse html for a long time after reading the first answer on http://stackoverflow.com/questions/1732348/regex-match-open-tags-except-xhtml-self-contained-tags!

share|improve this answer
show 1 more comment

I think clean humour, in small quantities, and not detracting from any real documentation is to be encouraged. Yes, code is ridiculously dry sometimes, and it can help break the frustration (especially if someone got frustrated right where you are, it can even help).

Today, while delving into some truly grisly leftovers I commented to a co-worker about the number of Yoda conditionals in the code... shortly later he had identified several variations on the theme... it helped the work go by easier.

Cheers

share|improve this answer
show 2 more comments

As long as your humor is PG-13, not insulting toward coworkers and doesn't distract someone from their job, I don't think anyone would have a problem with it.

share|improve this answer
add comment

Provided your code is polished, well documented and readable, then the odd funny comment is a good think. As long as it doesn't detract from the code readability, and isn't offensive.

It pays to make it obvious its a joke though, you don't want anyone thinking its some sort of cryptic documentation, and waste time figuring out what it means. Keep the jokes simple, avoid anything too obscure =P

share|improve this answer
add comment

Produce interesting, though-provoking and well-written comments that document code as concisely as possible without being boring.

This is not the same as strewing jokes and one-liners throughout a codebase. When I see this I invariably get angry that the developer has spent his time trying (and, often, failing) to make me laugh rather than actually doing the job that he was supposed to be doing.

In conclusion, there is a difference between writing something interesting and writing something funny. Code comments are no place for irrelevancies.

share|improve this answer
show 2 more comments

In my worst case, I would need to defend something I wrote in front of a Coroner or Criminal court, how much humor is appropriate?

For everyone else, it must add more value than the less humorous version, and not be done out of anger or frustration. It must be professional. How would you feel if you boss showed it to your customer in a meeting with Marketing and Sales? Would you just reinforce the stereo type of SW engineers being socially inept geeks?

Remember anything you put into version control is sealed there for ever, and just like all software, it will eventually escape into the wild.

share|improve this answer
add comment

If you ask for permission for humor, you're doing it wrong.

Make a joke if ... and only if ... and if ... - well, no, better stop it then. It will not be funny, if you pull over rubber gloves before touching it.

If you fear your coworkers, bosses and customers, you're doing it wrong. Change your job. Quit. Get a life!

share|improve this answer
show 1 more comment

The problem is clearly maintenance. What happens, if the code changes, but the joke will not (or worse, cannot) be adapted? Or if unit test failure gets so funny, that programmers actually want the tests to fail...

No. Stick to the enterprise-proven "Monkey with a Keyboard" approach and you're safe from these mundane, humanly and totally unplanable problems.

On a different note: If you put together HTML, you might indeed think twice, before putting fun in comments and pushing that out into the world, viewable to everyone, who can reach Ctrl and U at the same time on his keyboard.

share|improve this answer
add comment

At the end of every class in my framework I am building includes two lines of comments.

// I SEE THE LIGHT
// I SEE THE END

Basically because can only just see the end of my finishing the project after miles of tech docs I've been writing etc

share|improve this answer
add comment

I think it depends on the scope of the project. If it's just one person writing the code, then it doesn't matter as much. Otherwise I would say that there should be some constructive commenting in there just so other programmers understand what the code is doing. Again it depends on the audience.

In looking through some code in Facebook's API, there was some commenting that I found humorous. I think seeing as Facebook is large company making lots of money and all that, they can get away with a bit of humor. They're gonna have a large audience for the API's just because it's Facebook.

Also I think my example demonstrates that what is funny is dependent on one of two factors.

  1. Whether person writing the code intended the comment to be humorous.
  2. Whether the person reading the comment finds the comment humorous.

Kind of addresses the fact that some jokes just aren't really that funny and that some things that weren't intended to be humorous are funny to someone.

share|improve this answer
add comment

Actually my fist Programming tutorial I made was full of humor. It always made funny introduction of new features of that programming language. I totally agree to humor in technical documentaions, having a laugh at work can't be bad. But I think humor does only work in one direction. If you are a teacher or something in that direction then you are allowed to make jokes, its also a good motivation for all people who have to learn all that technical details. But as long as you are a student, you should be more carefull with jokes.

Everybody loves funny teachers, but funny students don't get the best marks.

share|improve this answer
add comment

If I write something particularly complex I will usually add something like:

 # Here be deep magiks. Bitches be thinkin' I'm Harry Potter, yo.
share|improve this answer
1  
While I think mild, occasional humor in code is perfectly fine, this is a stellar example of when it's NOT ok. –  Bryan Oakley Mar 5 '12 at 15:59
show 1 more comment

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.