“There are 2 hard problems in computer science: cache invalidation, naming things, and off-by-1 errors.”
Phil Karlton / Leon Bambrick
Recently, I have been working again more with already existing APIs. While these APIs are quite old and I used to know them, there are some things which quickly annoyed me.
And which – as I remember – annoyed me very much in the past.
Which led to errors and mistakes.
Which led to many misunderstandings.
I think everyone of us has spotted names that do not readily talk to us, and this is always a bad sign. At least I have seen this frequently throughout my career and the older I get the more I dislike them. But rambling about bad names is not going to change anything. So what to do?
So nothing has really changed with the APIs I am required to use but at least I had some time and mental distance to better analyze the situation. As such, I recognized why these APIs are hard to use and why there are so many misconceptions about what certain functions do and what their business sense is. Obviously, it is bad naming. But bad naming can come in many different shapes and forms (and depending on your syntax highlighting different colors). In the last days I stumbled across doGenericLandRegisterCase, makeF10, and doBusiness for operations and highlights like Number for message elements. These are obviously bad names because they convey little to absolutely no meaning. Many books have been written about them but bad names are like the yearly flue or zombies: they always resurface.
Rule: Avoid Generic Terms
The rule “Avoid Generic Terms” is the easiest to grasp and probably the one that will improve your names instantly and noticeably. From the examples above make and do are forbidden words. They are sooooo generic. An operation will do something by definition. So you should not mention that. Make is double the characters without conveying anymore meaning, so it’s even worse. In the same category is a frequently encountered word in identifiers: handle. However, this is also often used as the noun handler. Never use them in an operation name unless you want to quit your job anyway and hate your co-workers so that you want them to guess years down the road what the system is doing.
Very often do and make are used in names which carry the operation intent in the name as well. For example I found doRequestContractSigning. Simply eliminate the do and you are better of.
Besides generic verbs there are also generic nouns. Something is bad because it is abstract and meaningless. The same holds for thing, which at least is shorter but can also be eliminated without problems: doSomething is not better than do and is not better than no identifier if the compiler would not complain. From the examples below doBusiness is meaningless and you have to inspect the code (or documentation if there was any) to make sense of it.
This is no rocket science. Simply by removing or replacing these words, you can make your names much better.
|Bad Name||Better Name|
|doBusiness||(that really depends on your context)|
|Number||Identifier, Amount, …|
|doRequestContractSigning||requestSignature, requestApproval, signOffContract…|
Forbidden Words in Identifiers
So here is your list you can use in any code review (or API review) about words that must not appear as parts of identifiers:
- generic *
Words marked with an (*) may sometimes be justified but will still signal hard and error-prone operations.
By simply following this rule alone, your code will be a better place. If you want to dive deeper into better (and shorter) names, I can recommend you a video of a talk by Kevlin Henning which talks about my “things” but also a lot about good names. Another good resource, which I can recommend, is the book Clean Code by Robert C. Martin, which also dives into good naming. However, if you want your code or other people’s code to quickly improve, just ask yourself if the name or any portions of it are just generic words.