Naming Builders and Manipulators in Java

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 saveFile() or getTitle() don't fit and must be renamed and refactored. Moreover, methods that "manipulate" must always return void, for example, print() or save(). Let's take a closer look!

The Night Of (2016) by Richard Price et al.

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:

interface Bookshelf {
  Book find(String title);
}

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 book():

interface Bookshelf {
  Book book(String title);
}

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:

interface Foo {
  float speed(Actor actor);
  Money salary(User user);
  File database();
  Date deadline(Project project, User user);
}

Here, on the contrary, are a few examples of badly named builders:

interface Foo {
  float calculateSpeed(Actor actor);
  Money getSalary(User user);
  File openDatabase();
  Date readDeadline(Project project, User user);
}

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:

interface Bookshelf {
  void add(Book book);
}

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.