Sunday, November 27, 2016

How to name a function - Coding in Style - episode 11



Welcome to Coding in style, a series of short videos about how to improve our code.

This is Dragos and you are watching the Episode number 11 where we talk about how to name functions and function parameters.

A few days ago I met a friend. “What are you doing these days?”, he asked. I replied: “Book”. “What do you mean?” he asked. “Swift 3”. “Are you are reading a book about Swift 3?” he said. “Yes, I do,” I replied. “Why didn’t say so?” he said.

Of course, this is not a real conversation as it would have been a strange one. But sometimes this is how we name our functions.

As we’ve seen in the previous episodes, the variables are the nouns of our code.

Similarly, the functions are the verbs. They show an action.

To check if a function name is good, you can have a chat with it:

“Hey function, whatcha doing?”

And the function should be able to reply:

“I [function name]”

You should be able to include the function name after “I” and make a valid sentence.

Let’s look at some examples:

"I dropDatabase" - yes
"I sortArray" - yes
"I user" - nop
"I database" - nop
"I createDatabase" - yes
"I databaseCreate" - sort of, but only if your name Yoda is

You can pick a capitalization rule and stick to it. For Swift, it is lower camelcase.

So dropDatabase is fine, but not dropDATABASE or drop_database.

This can be a bit weird in the case of a name that includes an abbreviation. For example HTML or HTTP.

For example, do you use formatHTML or formatHtml?

createURL or createUrl.

In my opinion, whatever you choose looks ugly, so just pick one and be consistent.

Be specific. The name should make it clear what is the purpose of the function.

For example, create is not a good one. createDatabase is better

Long names are okay.

Make the names as long as needed, but no longer than that.

For example, if you have a function createLocalDatabase and there is only one database, replace it with createDatabase.

Regarding the function parameters, apply the same rules as for variables. In couple words, the name of a parameter should be a good replacement in the sentence “my name is [parameter name]”.

Regarding the number of parameters, they should be as few as possible.

Here is what Uncle Bob (aka Robert C. Martin) says in his "Clean Code" book:

"The ideal number of arguments for a function is zero (niladic). Next comes one (monadic), followed closely by two (dyadic). Three arguments (triadic) should be avoided where possible. More than three (polyadic) requires very special justification—and then shouldn’t be used anyway."

How about methods? Obviously, we use the same rules.

But, BTW, do you know what is the difference between a function and a method? A method is a function that belongs to a class. So a function is a free bird. A method is a free bird that has been captured and put in a cage, called class.

What else? What are your ideas about naming a function?

That is about it for today. We talked about how to name a function. In a previous episode, more exactly episode 7, we discussed how to name entities in general and in episode 8 we talked about how to name a variable or a constant. Feel free to watch them for more details.

That’s about it for now. See you soon!

No comments:

Post a Comment