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?

Shopping list or how to name a function parameter

- Hunny!
- Yes, hunny!
- Can you please run to the store and get few things?
- For sure, hunny! What do you need?
- I need bread, eggs, cheese, milk, apples and pears. Get 2, a dozen, a pound, 2 litres, a bag and 4 or 5!

*

Funny eh? This is how some language define the functions. Luckily, Objective C and Swift are different. You can use named parameters that makes the life easier.

Here are some rules for naming the parameters:

Whacha doin' or how to name a function?

While the variables are the nouns of the coding (as we've seen), the functions are the verbs.

To be sure they have a correct name, ask them:

"Whatcha doin'?"

"I [function name]" should be the answer.

"I createDatabase" - is good.
"I sortArray" - is great.

"I user" - not that much.
"I database" - nop.

How to name your variables and your kids

Story one

Some time ago, I travelled in India and one of things that amazed me was that, after I was introducing myself, everybody was asking: “What does your name mean?”

"What do you mean what does it mean, it is a name, names mean nothing", I was thinking.

Of course I was wrong. Most of the names mean something:

John means gracious
Mary means sea
Will means of course will, desire
and so forth

Even my name Dragos, comes from Drag which means loved in Romanian. My Indian friends were amazed when I was telling them that.

Looking for the meaning of a name might help choosing a name for your kids.  Even if it is nicer to find out after you've already chosen one.

*

How about the variable we use in our code?

Refactoring the evil i, j, k

For the sake of argument, consider you have the following input data:

let userIds = [1,2,3,4,5]

let userNames = [

    1 : "John",

    2 : "Mary",

    4 : "James"

]

let userAges = [

    2 : 30,

    4 : 40,

    5 : 25

]

5x3=?

If you think you knew how to compute 5x3, well, after reading this, you will not be that sure

The Programmer's Oath

Read here the Programmer's Oath by Uncle Bob

And this is a shorter version: As I love my programming activities, I will always write code that I love.

How small should be a function

"A function should be smaller than small" :)

Read more here:

https://mmrs151.wordpress.com/2015/11/04/the-poetry-in-function/