You all know
There are only two hard things in computer science cache invalidation and naming things.
— Phil Karlton
I found the holy grail! The first one mainly bothers me when using my browser. The second one keeps me awake at night. For about a year I am now practicing a technique which has proven to work very well for me. Read on and find out if it works for you too. I can sleep better since.
The Five Steps
I know I am not the first one who “found” this technique. Martin Fowler described something similar lots of year ago in his famous Refactoring book. Anyway.
You know those moments? The new code is in your fingers, but in order to type it out you need a function to call.
What shall it be named? If you are at that point apply the following rules and it makes function naming less stressful (and you can keep following your train of thoughts).
1) Create the function with the name “foo” (or “___”).
2) Find a good sentence that describes what the function does. Put it above the function as a comment.
function foo(s){}
3) Shorten the sentence until you think it contains the real core of what the function does. This sometimes takes time.
function foo(s){}
4) Create the function name by extracting the essence of the comment, mostly that just means removing words like “a”, “the”, “it”, etc.
function findCityByName(s){}
5) Remove the comment. Its only duplication anyway.
Congratulations. You should have a good function name.
Don’t be afraid to rename it later. Mostly there is a better name, it will come when you don’t expect it.
When Functions Are Born – Step 1
Functions get created in two cases. They get extracted from existing code. Or new code has to find a place to reside in.
In the “extract method” case the naming is normally pretty simple. The extraction is done on purpose, you want to separate concerns. In some cases there is even a comment that just separates various blocks inside a bigger function, like here:
if (typeof s == 'number') {
// find city by zip code
implementation;
} else if (typeof s == 'string') {
// find city by name
implementation;
}
}
That comments on line 3 and 6 can just be used to create the function name from. If that is the case go to step 3.
The creation of a new function is more common to have the problem of getting the right name. I like to make sure I don’t leave unnamed or badly named functions around (for too long). But in order to have the tests pass (leave them red as short as possible) I start off naming my functions “___” (“foo” is fine too). All tests green – good.
Back to naming – I always use the underscores so every time I look at it the source code just looks strange. And this will never get committed, since the diff check I do before every commit turns on all my alarm bells when there are names like that around. For me the string “foo” would not be so easy to spot, visually.
There is another good reason, why “foo” or “___” are better names than “get” or “set”. When you later use your IDE’s refactoring feature for renaming functions the latter might occur in many places and in other libraries and your IDE might want to rename more than you wish, since most JavaScript IDE’s refactoring features are still based a lot on string matching. And the probability that someone used a function “foo” or “___” is pretty low. So also renaming should work like a breeze.
Leave Function Unnamed
Do those “ugly” function names (“foo” or “___”) stick around? Sometimes. Always when I tried to give a function a name but didn’t succeed. In those cases I really leave the old name. I keep implementing the surrounding pieces and since the context and responsibility of the function becomes clearer the name will eventually come naturally too.
Describe
The function naming was always something that really bothered me. I mostly ended up with a bad name, or with the feeling of not having hit the nail on it’s head. Or just with inconsistent naming schemes throughout the source code. Yes, also here refactoring comes into play and I use it heavily.
But finding a good name from the beginning makes everything afterwards easier. You know the real reason of this function, you described it well. You have the burden off your back to rename that function later. You have no comments to maintain that try to explain what the function does.
Describing the function in proper english using a real sentence(!!!) that ends with a period makes it quite easy to 1) find a good name and 2) to get much better at consistency in naming.
The shortening part is just a matter of doing it. It takes practice, and you might laugh: it also takes courage. Source code lives and it should change. I am not afraid anymore of changing comments or function names.
Creating sentences like: Convert the data. Are just too generic. Try again. Maybe: Convert the article list from CSV into JSON. Oooh, do you see it? Additionally this might indicate that you are not writing something specific that no one has ever done before. I let you continue these thoughts here …
Getting it done
Extracting the function name from the shortened sentence should be a piece of cake now. Of course the standard rules for naming, such as prefix with “is”, “does”, etc. when it just returns a boolean, apply.
If writing out the function name still seems hard go back to step 3 and shorten even more. Don’t worry about long names they will be pointers to how to restructure, but that is another article of it’s own.
Sooo much text for describing something that does not even take a minute. Sorry gals. But I hope it was helpful.
One hard thing in computer science (partly) solved. Half of the holy grail :).
