Does humor belong in javadocs? | Java.net

My pages	Projects	Communities	java.net

Get Involved About java.net Request a Project Publicize your Project Submit Content java-net Project Java.net Enhancements Site Help Report Inappropriate Content Get Informed Articles Blogs Events java.net Online Books java.net Archives Get Connected java.net Forums Wiki Javapedia People Partners Jobs RSS Feeds Java User Groups Search Web and Projects: Online Books: java.net on MarkMail: Advanced Search
		Does humor belong in javadocs? No, it's unprofessional 34% (303 votes) Yes, it lets off steam and reveals developers' thinking 61% (535 votes) Javawhats? 5% (43 votes) Total votes: 881 » Login or register to post comments 365 visits Printer-friendly version JUnit Javadoc Submitted by dserodio on Wed, 2005-11-09 07:02. Check the Javadoc for JUnit's TestSuite.createTest() method: `/** * ...as 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?* Login or register to post comments Humor in Javadocs, NO! Submitted by jlbalder on Thu, 2005-08-18 09:47. 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". Login or register to post comments A Developer Walks Into A Bar In Redmond... Submitted by jfrosch on Wed, 2005-08-17 22:23. If we can make fun of certain monopolies and their developers in JavaDocs, I guess I'm okay with it.. :-) Jack Login or register to post comments Foo/bar Submitted by javakiddy on Wed, 2005-08-17 03:32. 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. Login or register to post comments Unprofessional Submitted by erickson on Tue, 2005-08-16 10:48. 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. Login or register to post comments humor is easy to misunderstand Submitted by binstock on Tue, 2005-08-16 08:06. 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. Login or register to post comments There's only one solution Submitted by gbarton on Mon, 2005-08-15 17:29. A new Javadoc tag! Login or register to post comments There's only one solution Submitted by gbarton on Mon, 2005-08-15 17:30. Oh, for frack's sake. Login or register to post comments NO! Submitted by parmenion0 on Mon, 2005-08-15 04:56. 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. Login or register to post comments if appropriate Submitted by jwenting on Mon, 2005-08-15 04:00. 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. Login or register to post comments Humor , why not? Submitted by hercules on Sat, 2005-08-13 20:13. 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. Login or register to post comments Humans or robots ? Submitted by felipegaucho on Sat, 2005-08-13 15:20. 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. Login or register to post comments No humour Submitted by elpinturrichio on Sat, 2005-08-13 05:23. I agree... humourous comments is not what software documentation is about Login or register to post comments Humor can be misunderstood Submitted by dog on Fri, 2005-08-12 07:54. Humor can be misunderstood.. especially if you have people from many countries working on your project. Login or register to post comments Humor can be misunderstood Submitted by rickcarson on Sun, 2005-08-14 21:13. 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. Login or register to post comments Humor can be misunderstood Submitted by killerdm on Wed, 2005-08-17 11:21. 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. Login or register to post comments Humor can be misunderstood Submitted by pholthuizen on Sun, 2005-08-14 05:03. 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. Login or register to post comments Humor can be misunderstood Submitted by jmelchio on Sat, 2005-08-13 07:21. 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. Login or register to post comments