Skip to main content

Does humor belong in javadocs?

No, it's unprofessional
34% (303 votes)
Yes, it lets off steam and reveals developers' thinking
61% (535 votes)
5% (43 votes)
Total votes: 881


JUnit Javadoc

Check the Javadoc for JUnit's TestSuite.createTest() method: /** * the moon sets over the early morning Merlin, Oregon * mountains, our intrepid adventurers type... */ static public Test createTest(Class theClass, String name) { Constructor constructor; try { WTF?

Humor in Javadocs, NO!

I love humor. I collect Dilbert, Calvin & Hobbes, and many other pieces of humor as they relate to the human condition. But one of the things that particularly disturbs me is the rampant gratuitous humor in (my particular peeve) computer manuals and tutorials. If I want humor, I'll buy a Dilbert book. What I want in documentation is the 'just the facts, maam'. An excellant example of simple factual documentation is the book by Khalid Mughal and Rolf Rasmussen, "A Programmer's Guide to Java Certification: A Comprehesive Primer, Second Edition".

A Developer Walks Into A Bar In Redmond...

If we can make fun of certain monopolies and their developers in JavaDocs, I guess I'm okay with it.. :-) Jack


Let us not forget the infamous Foo and Bar (originally FUBAR) which has appeared in many a piece of documentation.

Small jokes which do not detract from the quality of the documentation are fine. Note, for example, Python's (mandatory !) use of the the terms 'eggs', 'beans' and 'spam' in any source code examples. Easter eggs (like the chicken story which used to be hidden in Borland C++ documentation) I suppose are acceptable too in small numbers.

I don't think anyone is seriously suggesting programming documentation should read like the transcript of a stand up routine.


Real professionals put their humour where real professionals will see it, in /* */ and // comments. When Javadocs give no hint of the coder's uproarious wit, it maximizes the impact of the sidesplitting laughs that ensue when another coder is hunting for your NullPointerExceptions.

humor is easy to misunderstand

Humor exists only within a known cultural context. People who are not part of that context can easily miss the humor or, worse, think that the comment is a true part of the docs and become confused. I like my docs to be clear, unambiguous, and informative. I don't see how humor advances that.

There's only one solution

A new Javadoc tag!

There's only one solution

Oh, for frack's sake.


All I want from your javadoc is a clear idea of what the method and it's parameters does. Humour doesn't add any useful information. If you must put laughs in, put them in regular comments next to the funny piece of code. Don't put in jokes that aren't about the code. And if I see another stupid reference to B-grade "humour" like Monty Python or Douglas Adams I'm going to crack and administer 12-gauge justice to the offender.

if appropriate

Developers typically share a sense of humour (at least to a degree) and I see nothing wrong with that being reflected in their documentation.

Just check the number of allusions to the Hitchhiker's Guide to the Galaxy, Monty Python, etc. in books and example code.

But humour should be mostly harmless. I draw the line at openly sexist or racist humour (even if meant as being humorous). That means no stupid blonde jokes either (having 2 of them as analysts/testers in the same room with me pretty much voids that option anyway :) )

So: humour: yes, but in moderation.

Humor , why not?

As long as the humor is tasteful and within the context of the app , I think it makes sense. For example if you had javadac describing a method that returns an irrational number, you could make a joke about the programmer being irrational.

Humans or robots ?

yes, we are humans and we have humor too.. if a javadoc contains all information needed to a good maintenance, why not include tips about the moment where the code was produced ? team stress comments, funny bugs and "good luck" to the next programmer... let the dry javadoc to the robots.

No humour

I agree... humourous comments is not what software documentation is about

Humor can be misunderstood

Humor can be misunderstood.. especially if you have people from many countries working on your project.

Humor can be misunderstood

I agree with dog. Even if the other country speaks the same first language as you do, they just might not get the cultural references. Eg in NZ the word 'bugger' is screamingly funny to everyone. Whereas in Queensland they have a lot of weird words for common things and they don't really do the dry/sardonic British type humour. I haven't watched endless reruns of "I love Lucy" and "Gilligans Island" so there are a bunch of references I just don't get.

Consider the difference between the movies Shrek I and II... #1 is timeless, whereas #2 is all about hollywood, and is packed full of modern cultural references that will age very very quickly. To someone that spends very little time watching US TV #2 just wasn't all that funny.

Humor can be misunderstood

Who cares if it is misunderstood? What is the harm is some reference passes harmlessly over my head? Yes, humor is tied closely to the culture of the individual but no harm is done. Personally, if someone from New Zealand or England makes a joke in a Javadoc and I as an American read it, at worst it will pass harmlessly over my head and at best maybe I'll gain some insight and appreciation for their culture.

Humor can be misunderstood

There is nothing wrong with humor but it can be confusing if it gets mixed up with the serious content as API documentation is often hard enough to understand.

Maybe a seperate link to a seperate page with some humorous comments and background information would be acceptable, though I hope the same attention is being spent on the serious part of the documentation.

Humor can be misunderstood

Comments can be misunderstood without humor as well. For some reason people sometimes people think that joking around shows a lack of professionalism but I don't believe that at all.
You can have a sense of humor and have an urge to express it and be very serious about your profession at the same time.