There are forbidden words that you should avoid to use by all means necessary when naming operations, functions, or methods.
For example, starting your names with
Introduction
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
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
Very often
Besides generic verbs there are also generic nouns.
Improved Names
This is no rocket science. Simply by removing or replacing these words, you can make your names much better.
Bad Name | Better Name |
---|---|
doGenericLandRegisterCase | registerCaseWithLandRegistry |
makeF10 | executePayment |
doBusiness | (that really depends on your context) |
Number | Identifier, Amount, ... |
handleAsyncCallback | updateAssetStatesAfterTransferCompleted |
doRequestContractSigning | requestSignature, requestApproval, signOffContract... |
There are probably many more bad but easily fixable identifiers. If you have some, please drop me an email or a tweet.
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:
- do
- make
- handle
- perform
- something
- thing
- object
- manager
- part
- item
- 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.
<<< Previous Blog Post Easily Spoting Problems in Your Process With BPMN - COVID Edition |
Next Blog Post >>> Why Germany failed to combat COVID-19: inefficient bureaucracy and no technology |