The easiest rule to not give bad names for your APIs and operations: No generic terms!
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
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
Besides generic verbs there are also generic nouns.
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.
Subscribe to get notified for new articles!
There are more articles to come. If you want to stay informed, please leave your email address to get notified!
Dr.-Ing. Daniel Lübke is a Digital Solution Architect, who enjoys realizing high-quality business processes in software. He has over 10 years experience in architecture of distributed systems (from SOA to Microservices, BPM and workflows). Daniel likes to find better than "state of the art" solutions by combining methods from Software Engineering and BPM, in addition to researching promising, uncommon solutions. He is book author, editor, and speaker at conferences, and has published many articles in different magazines and journals.