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 do or make is the best way to create one of the worst identifier names. So let's dive into it.

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 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.

Improved Names

This is no rocket science. Simply by removing or replacing these words, you can make your names much better.

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.

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.

>>> You can find more information in his profile