Naming Builders and Manipulators in Java
Want to learn more about naming builders and manipulators in Java? Check out this post to learn more about OOP and naming objects.
Join the DZone community and get the full member experience.Join For Free
There is a simple principle for naming methods in OOP. I'm trying to demonstrate this in the following code — it's a verb if it manipulates; it's a noun if it builds. That's it. Nothing in between. Methods like
getTitle() don't fit and must be renamed and refactored. Moreover, methods that "manipulate" must always return
void, for example,
save(). Let's take a closer look!
First, I have to say that this idea is very similar to the one suggested by Bertrand Meyer in his book Object Oriented Software Construction, where he proposes we divide an object's methods into two sharply separated categories: queries and commands.
The idea behind this principle is rather philosophical. Let's start with builders, which are supposed to create or find an object and return it. Suppose I have a store of books, and I ask it to give me a book by name:
It's obviously a "builder" (or a "query" in Meyer's terms). I ask for a book, and it's given to me. The problem, though, is with the name of the method. It's called "find," which implies that I know how the book will be dealt with. It will be found.
However, this is not how we should treat our objects. We must not tell them how to do the job we want them to do. Instead, we must let them decide whether the book will be found, constructed, or taken from a memory cache. When we query, we have to say what result we are looking for and let the object make the decision about the way this result is going to be built. A much more appropriate name for this method would be
The rule of thumb is that a builder is always a noun. If the method returns something, it has to be a noun. Preferably, its name should explain what the method returns. If it's a book, name it
book(). If it's a file, call the method
file(), etc. Here are a few builder examples:
Here, on the contrary, are a few examples of badly named builders:
There is no place for a verb in a builder's name!
It's not only about the name, by the way. A builder, since its name doesn't contain a verb, should not do any modifications to the encapsulated entities. It may only create or find something and return it. Just like a pure function, it must not have any side-effects.
Next, there are "manipulators" (or "commands" in Meyer's terms). They do some work for us, modifying the entities, which the object encapsulates. They are the opposite to builders because they actually make changes to the world abstracted by the object. For example, we ask the
Bookshelf to add a new book to itself:
The method adds the book to the storage. How exactly the storage will be modified, we don't know. But, we know that since the name of the method is a verb, there will be modifications.
Also, manipulators must not return anything. It's always
void that we see as the type of their response. This is needed mostly in order to separate the imperative part of the code from the declarative part. We either receive objects or tell them what to do. We must not mix those activities into one method.
The purpose of these rules is to make the code simpler. If you follow them, and all your builders only return objects and your manipulators only modify the world, the entire design will become easier to understand. Methods will be smaller and their names shorter.
Of course, very often you will have a hard time finding those names. From time to time, you will want to return something from a manipulator or make your builder make some changes, say to the cache. Try to resist this temptation and stay with the principle: a method is either a builder or a manipulator — nothing in the middle. The examples above are rather primitive; the code in real life is much more complicated. But, that's what this principle is going to help us with — making code simpler.
I'm also aware of the noun/verb principle, which suggests always naming classes as nouns and their methods as verbs. I am not a huge fan of this idea since it doesn't differentiate builders from manipulators and encourages us to always think in terms of imperative instructions. I believe that OOP is more about the declarative composition of objects, even if we have to sometimes get them from other objects, instead of instantiating them via constructors. That's why we need builders in most situations, and we also have to see an obvious difference between them and the other methods or manipulators.
You can find a more detailed discussion of this problem in Elegant Objects, Volume 1, Section 2.4.
Published at DZone with permission of Yegor Bugayenko. See the original article here.
Opinions expressed by DZone contributors are their own.