37

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?

Improve this question
7
  • Please read the site's FAQ and guidelines to asking questions. This question really doesn't meet those guidelines.
    – Walter
    Mar 22, 2011 at 11:40
  • 8
    @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, 2011 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, 2011 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, 2011 at 13:29
  • 1
    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, 2011 at 1:37

11 Answers 11

Reset to default
12

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?

Improve this answer
5
  • 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, 2011 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, 2011 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, 2011 at 21:42
  • @glasnt - that's a genuinely funny comment - but it would irritate on iteration 2, and increasingly irritate subsequently!
    – amelvin
    Mar 22, 2011 at 22:58
  • Allowing humor in comments is perfectly acceptable. Why make an already dry industry dry AND humorless? Allowing swearing or insults or maliciousness is an entirely different matter. My experience has been totally different from yours. I've chuckled many a time reading informative comments that exhibited a witty sense of humor. It made my day better. It takes some intelligence to be tasteful in one's humor, but if it can be done with maturity, bring it on.
    – Reverse Engineered
    Oct 23, 2018 at 8:17
72

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.

Improve this answer
15
  • 9
    +1 For "Professional but Funny"
    – deworde
    Mar 22, 2011 at 12:33
  • Programming is itself fun :)
    – Gopi
    Mar 22, 2011 at 12:48
  • 2
    @Sri Kumar: Unfortunately, not always. :(
    – Bobby
    Mar 22, 2011 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, 2011 at 12:56
  • 3
    +1 for not taking yourself too seriously.
    – JeffO
    Mar 22, 2011 at 13:30
8

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.

Improve this answer
2
  • 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, 2011 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, 2011 at 13:37
8

Code is meant for reading... many times.

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

Improve this answer
14
  • @Thorbjørn Ravn Andersen: what about Dilbert cartoons you print and pin on your cubicle wall? ;)
    – user2567
    Mar 22, 2011 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, 2011 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, 2011 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, 2011 at 15:37
  • @Thorbjørn Ravn Andersen: that's the only one
    – user2567
    Mar 22, 2011 at 15:44
7

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 ;)

Improve this answer
1
  • I disagree with my old self
    – Reno
    Jun 10, 2021 at 9:22
6

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)
Improve this answer
4
  • 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, 2011 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, 2011 at 12:39
  • In that situation I would be pretty pleased too
    – somebody
    Mar 22, 2011 at 12:41
  • Do not put line numbers, use "search for <whatever>" instead where <whatever> is itself a comment.
    – Vinko Vrsalovic ♦
    Jun 26, 2012 at 10:16
3

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.

Improve this answer
3

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.

Improve this answer
2

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.

Improve this answer
2

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.

Improve this answer
1

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...

Improve this answer

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