How to NOT comment your code

Researching for the yesterday's post ("Look, I am playing tennis" or how to document your code), I stumbled on a interesting topic, and that is "funny comments".

While initially the post advised against it, I found some that are really funny so I would like to list some of them here. While they are not useful, they do increase the quality of the code by making the other developers laugh.

But there is a danger that some might not get our humour so when in doubt, better don't add it.


/**
* For the brave souls who get this far: You are the chosen ones,
* the valiant knights of programming who toil away, without rest,
* fixing our most awful code. To you, true saviors, kings of men,
* I say this: never gonna give you up, never gonna let you down,
* never gonna run around and desert you. Never gonna make you cry,
* never gonna say goodbye. Never gonna tell a lie and hurt you.
*/


// Dear maintainer:
// 
// Once you are done trying to 'optimize' this routine,
// and have realized what a terrible mistake that was,
// please increment the following counter as a warning
// to the next guy:
// 
// total_hours_wasted_here = 42

"Look, I am playing tennis" or how to document your code

Serena Williams playing tennis

Useful? Not really.

Serena Williams playing tennis at the Australian Open 2010

Useful? Yes! Required? Partly! Everybody who cares about tennis knows who she is.  Also, even a small kid can see what she is doing.

Australian Open 2010

Now you are talking

*

Here are 10 quick rules about documenting your code:

1. Say something useful that is not obvious from the code:

var age = 10

//incrementing the age

++age

No kidding?!?

Content hugging vs. compression resistance in Apple's auto layout

Auto layout is a great way to define UI when developing Apple software.

"Auto" means it does a lot by itself. You define some rules and the engine is calculating the size of the screen elements.

There is one case when it cannot.

Consider two labels, side by side:



All is good, each label is taking as little space as possible.

We would like to extend the labels in such a way that they will cover the whole screen, with a little bit of space on the sides and at the back.

Layout engine is confused this time: which one should grow? You might say: equally. That might be okay, but what if the labels contain different amount of text?