Question

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?

No correct solution

Licensed under: CC-BY-SA with attribution
scroll top