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.

I want to ask you whether adding some "easter eggs" in the source documentation is unprofessional or not. Probably you have read the StackOverflow poll for funny comments in a source documentation, and I have personally stumbled at many such things during my work, including funny (or not) stuff in public API documentation (for example this weak BZZZTT!!1! thing in Android public documentation, I can give at least a dozen more examples).

I can't come to a final opinion for myself, because I have contradicting arguments by myself.

Pro argument:

  • It can cheer up somebody, and make his/her day funnier/more productive. Major portion of the source code doesn't need to be commented anyway (if the project is done properly), because the specific method (for example) is self explanatory, or if it is a pile of strange crappy code, it can't be explained in a meaningful way, so a funny joke doesn't harm the possible info that you can obtain from the doc.

Cons argument:

  • If you are very concentrated/frustrated, the last thing you need is somebody's stupid joke, instead of giving you information you need about the documented code portion, it can just make you even more frustrated. And the idea of what the documentation would look like if everybody starts doing so is horrible. Plus the guy who writes the joke may be the only one who thinks that it is funny/interesting/worth wasting time to read it.

What do you think?

share|improve this question

closed as not constructive by JeffO, Walter, Jonathan Khoo, FrustratedWithFormsDesigner, Fanatic23 Mar 22 '11 at 14:05

As it currently stands, this question is not a good fit for our Q&A format. We expect answers to be supported by facts, references, or expertise, but this question will likely solicit debate, arguments, polling, or extended discussion. If you feel that this question can be improved and possibly reopened, visit the help center for guidance.If this question can be reworded to fit the rules in the help center, please edit the question.

    
Please read the site's FAQ and guidelines to asking questions. This question really doesn't meet those guidelines. –  Walter Mar 22 '11 at 11:40
7  
@Walter : it is pretty much the same question as programmers.stackexchange.com/questions/50928/… , but for funny comments instead of profanity comments, and the linked question is not closed, asked a month ago. I won't waste time arguing with you that this question meets the FAQ, and that it is related to best (good) practices when writing code. –  somebody Mar 22 '11 at 11:42
2  
7 votes, this Q is clearly wanted. Personally I don't cos I've been pissed off by the "con" you've mentioned to many times but I can see the arguments for "pro" so I'm curious what the outcome is. (The worst I encountered btw was a programmer who thought a "hilarious" photo of a BB gun pointing at a kitten with it's paws up must be on the home page of all our dev servers. Sigh ...) –  James Mar 22 '11 at 12:44
    
@sombody - You have a point, but funny comments are not as likely to get you fired or worse, subject to a harassment suit. I'll consider closing the other question (Not sure I had that right when it was posted.). –  JeffO Mar 22 '11 at 13:29
    
I agree that this post should be re-opened, although I can't vote cause I don't have the rep. The whole point of making Programmers separate from SO is for questions such as this. Plus with 22 votes for this question, it is clearly wanted by the community. –  RoboShop May 25 '11 at 1:37
show 1 more comment

11 Answers

up vote 12 down vote accepted

I think that funny comments waste time - wasted time to write, wasted time to read, wasted time to show to your colleagues the funny remark that is (almost always) merely puzzling and so on.

But ... no-one actually works at 100% all day every day (sites like this would be empty if we did) and genuine humour breaks up the day and helps maintain morale.

I would still vote against it simply because every 'funny' comment I've ever read may well have been hilarious at the time - but I've yet to see one that actually funny, most are merely puzzling or are a deep-down in-joke.

If funny comments were actually funny it would change my mind. But once you encourage jokes, do you encourage swearing or insults or maliciousness?

share|improve this answer
5  
+1 You only read those comments when you have to fix something and they don't make any sense then and when bugfixing you certainly aren't in the mood to see some other developer's 'clever joke' about the subject. Instead of spending time on thinking of a joke, please, spend some time on clearer code, fix a bug, etc. Also, what happens with the 'joke' if something got refactored? –  Jan_V Mar 22 '11 at 11:52
2  
So it's just like humor in meatspace: it better be funny, and it better not be ALL you do. –  Dan Ray Mar 22 '11 at 13:06
1  
+1 clever, as long as it does no harm. Putting stop() //hammertime at every instance of stop isn't funny. –  glasnt Mar 22 '11 at 21:42
    
@glasnt - that's a genuinely funny comment - but it would irritate on iteration 2, and increasingly irritate subsequently! –  amelvin Mar 22 '11 at 22:58
add comment

I'm a big fan of funny commenting.

You should always be professional in your commenting, but some humor won't kill the reader.

Especially if the reader is a member of your team.

What I dislike the most, is developers that take themselves too seriously. I think we should have fun at work, or work is not worth it.

share|improve this answer
9  
+1 For "Professional but Funny" –  deworde Mar 22 '11 at 12:33
    
Programming is itself fun :) –  Tech Jerk Mar 22 '11 at 12:48
2  
@Sri Kumar: Unfortunately, not always. :( –  Bobby Mar 22 '11 at 12:54
1  
@Bobby: take the decision to make it fun then! If they won't let you, go bring your happiness to a company that deserve it. –  user2567 Mar 22 '11 at 12:56
3  
+1 for not taking yourself too seriously. –  JeffO Mar 22 '11 at 13:30
show 10 more comments

If it has meaning, it's fine to be funny. Explaining something in a comment in an amusing way is fine. However, if it's only something funny and contains no actual value as a comment, thats just annoying. Always keep in mind that the reason for comments is to make maintenance more efficient. Humor doesn't have to conflict with that, but could if not done appropriately.

share|improve this answer
1  
+1 Exactly my perspective –  pdr Mar 22 '11 at 12:37
    
There's a comment in a critical program's error handling code: "Life's a _ and then you die." at the end of the explanation. It's funny and it makes sense. –  Michael K Mar 22 '11 at 13:34
1  
@Michael - That's a perfect example of what I think is a waste. It's not funny (being yet another repetition of a very old and tired statement) and adds nothing of value. –  Brian Knoblauch Mar 22 '11 at 13:37
add comment

Code is meant for reading... many times.

How many jokes do you know that are funny after the hundredth telling?

share|improve this answer
    
@Thorbjørn Ravn Andersen: what about Dilbert cartoons you print and pin on your cubicle wall? ;) –  user2567 Mar 22 '11 at 14:56
    
@Pierre, if you find a single Dilbert suitable for putting in a source code comment, please let me know. –  user1249 Mar 22 '11 at 15:14
    
@Thorbjørn Ravn Andersen: not Dilbert, but this one deserved the space it takes : i.imgur.com/tu7Fd.jpg –  user2567 Mar 22 '11 at 15:17
    
@Pierre, actually I consider the wording in that poster over the limit and not funny, but that is another matter. How many more do you have? –  user1249 Mar 22 '11 at 15:37
    
@Thorbjørn Ravn Andersen: that's the only one –  user2567 Mar 22 '11 at 15:44
show 9 more comments

Funny comments are great.

  • It give a positive vibe to your seemingly boring code.
  • If you get your timing correctly .It does much better explaining than a normal boring comment would. By 'timing' here I mean the relevance to the code below the comment.
  • Your code will be remembered by many, because emotions are given a better place in (human) memory. This is a great trick if you want more guys to work with you on an open-source project.
  • Generally helpful in reviews. It makes your code a lot more bearable. Of-course you should first concentrate on writing good code. I feel when one is confident with the code they write, funny comments are just a side effect.

Just don't be funny like this guy ;)

share|improve this answer
add comment

Here's one I wrote at two in the morning ("DQ" is my company's initials):

// Twas the night before go-live and all through DQ
// the devs were all crying and yes, this means you.
// Keys had been saved with both hyphens and 'scores
// which left this programmer with finger pad sores.
// The solution I crafted, you'll likely find lacking:
// to OR them together with judicuous hacking.

$hyphenated = str_replace('_','-',$data_type_key);
$underscored = str_replace('-','_',$data_type_key);
// (and then see line 46)
share|improve this answer
3  
Yes, such things are most likely to occur at 2 AM, but I don't thing that this is a good joke - somebody after you has to read 6 lines of text if he wants to see the comment for 2 lines of source. The same ratio as having to read 600 lines of essay that explains 200 lines of code –  somebody Mar 22 '11 at 12:34
5  
Oh, efficiency was out the window. This project was already such a cluster-you-know-what, a little levity went a long way toward 2am morale. If you notice, the code I'm writing here is to work around somebody else's sloppiness, which was pretty much what the last two weeks of death march was about. I don't condone this sort of thing as a regular practice, but I confess I was pretty pleased with this one. –  Dan Ray Mar 22 '11 at 12:39
    
In that situation I would be pretty pleased too –  somebody Mar 22 '11 at 12:41
    
Do not put line numbers, use "search for <whatever>" instead where <whatever> is itself a comment. –  Vinko Vrsalovic Jun 26 '12 at 10:16
add comment

If you were reviewing your source code in front of the customer would you be embarrassed?

None of the current answers seem to take that into account. Some customers have no sense of humor and will take the jokes as an indicator that you do not take your job seriously. They will infer that you are careless with your work.

Funny code comments can sometimes be unprofessional and inappropriate.

share|improve this answer
add comment

Beyond what's already said, if you're working in international team, some of your overseas colleagues may not get the joke, because either of some local cultural references or some words' play that is not understood by someone for whom English is not native language. Same thing applies for open source projects.

share|improve this answer
add comment

If it is efficient and doesn't waste the readers time (in either reading/understanding) then I don't see a problem with a bit of humour.

share|improve this answer
add comment

Just like jokes in the real world, if you make them all the time it's not funny, not productive, and not professional. But there's a time and place for all jokes, and there's a time and place in code. Just like in the real world, it's knowing where, when and how to make the joke.

share|improve this answer
add comment

Depends, for assignments at college, I was almost always doing funny commenting, as I knew it will never be used and is just a homework assignment.

For more serious projects, I'd still use them here and there, but not as prevalent, so that it is annoying or hard to understand, defying the purpose of the comment.

I remember doing a bit of web programming, where I had to dodge browser incompatibilities and weird glitches. It sometimes ended in comments full of rage and hate in the .js files.

My basic rule of thumb is: If it's somewhat obvious what the code section does, FUNNY COMMENTS TURN ON!

If the code is so obscure and obfuscating as hell (like the "inline class"), I'd better be using comments I'll understand myself in a couple of days...

share|improve this answer
add comment

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