Why would a type be coupled with its builder?

Question

I've recently deleted a java answer of mine on Code Review, that started like this:

private Person(PersonBuilder builder) {

Stop. Red flag. A PersonBuilder would build a Person; it knows about a Person. The Person class shouldn't know anything about a PersonBuilder - it's just an immutable type. You've created a circular coupling here, where A depends on B which depends on A.

The Person should just intake its parameters; a client that's willing to create a Person without building it should be able to do that.

I was slapped with a downvote, and told that (quoting) Red flag, why? The implementation here has the same shape that which Joshua Bloch's demonstrated in his "Effective Java" book(item #2).

So, it appears that the One Right Way of implementing a Builder Pattern in Java is to make the builder a nested type (this isn't what this question is about though), and then make the product (the class of the object being built) take a dependency on the builder, like this:

private StreetMap(Builder builder) {
    // Required parameters
    origin      = builder.origin;
    destination = builder.destination;

    // Optional parameters
    waterColor         = builder.waterColor;
    landColor          = builder.landColor;
    highTrafficColor   = builder.highTrafficColor;
    mediumTrafficColor = builder.mediumTrafficColor;
    lowTrafficColor    = builder.lowTrafficColor;
}

_{^{https://en.wikipedia.org/wiki/Builder_pattern#Java_example}}

The same Wikipedia page for the same Builder pattern has a wildly different (and much more flexible) implementation for C#:

//Represents a product created by the builder
public class Car
{
    public Car()
    {
    }

    public int Wheels { get; set; }

    public string Colour { get; set; }
}

As you can see, the product here does not know anything about a Builder class, and for all it cares it could be instantiated by a direct constructor call, an abstract factory, ...or a builder - as far as I understand it, the product of a creational pattern never needs to know anything about what's creating it.

I've been served the counter-argument (which is apparently explicitly defended in Bloch's book) that a builder pattern could be used to rework a type that would have a constructor bloated with dozens of optional arguments. So instead of sticking to what I thought I knew I researched a bit on this site, and found that as I suspected, this argument does not hold water.

So what's the deal? Why come up with over-engineered solutions to a problem that shouldn't even exist in the first place? If we take Joshua Bloch off his pedestal for a minute, can we come up with one single good, valid reason for coupling two concrete types and calling it a best practice?

This all reeks of cargo-cult programming to me.

Answer 1

I disagree with your assertion that it is a red flag. I also disagree with your representation of the counterpoint, that there is One Right Way of representing a Builder pattern.

To me there's one question: Is the Builder a necessary part of the type's API? Here, is the PersonBuilder a necessary part of the Person API?

It is entirely reasonable that a validity-checked, immutable, and/or tightly-encapsulated Person class will necessarily be created through a Builder it provides (regardless of whether that builder is nested or adjacent). In doing so, the Person can keep all of its fields private or package-private and final, and also leave the class open for modification if it is a work in progress. (It may end up closed for modification and open for extension, but that's not important right now, and is especially controversial for immutable data objects.)

If it is the case that a Person is necessarily created through a supplied PersonBuilder as part of a single package-level API design, then a circular coupling is just fine and a red flag isn't warranted here. Notably, you stated it as an incontrovertible fact and not an API design opinion or choice, so that may have contributed to a bad response. I wouldn't have downvoted you, but I don't blame someone else for doing so, and I'll leave the rest of the discussion of "what warrants a downvote" to the Code Review help center and meta. Downvotes happen; it's no "slap".

Of course, if you want to leave a lot of ways open to build a Person object, then the PersonBuilder could become a consumer or utility of the Person class, on which the Person should not directly depend. This choice seems more flexible—who wouldn't want more object creation options?—but in order to hold to guarantees (like immutability or serializability) suddenly the Person has to expose a different kind of public creation technique, such as a very long constructor. If the Builder is meant to represent or replace a constructor with a lot of optional fields or a constructor open to modification, then the class's long constructor may be an implementation detail better left hidden. (Also bear in mind that an official and necessary Builder doesn't preclude you from writing your own construction utility, just that your construction utility may consume the Builder as an API as in my original question above.)

---

p.s.: I note that the code review sample you listed has an immutable Person, but the counterexample from Wikipedia lists a mutable Car with getters and setters. It may be easier to see the necessary machinery omitted from the Car if you keep the language and invariants consistent between them.

Answer 2

I understand how annoying it can be when 'appeal to authority' is used in a debate. Arguments should stand on their own IMO and while it's not wrong to point to the advice of such a well-respected person, it really can't be considered a full argument in itself ala we know the Sun travels around the earth because Aristotle said so.

Having said that, I think the premise of your argument kind of the same. We should never coupling two concrete types and call it a best practice because... Someone said so?

In order for the argument that coupling is problematic to be valid, there need to be specific problems that it creates. If this approach is not subject to those issues, then you can't logically argue that this form of coupling is problematic. So if you want to make your point here, I think you need to show how this approach is subject to those issues and/or how decoupling the builder will improve a design.

Offhand, I'm struggling to see how the coupled approach will create issues. The classes are completely coupled, for sure but the builder exists only to create instances of the class. Another way to look at it would be as an extension of the constructor.

Answer 3

To answer why a type would be coupled with a builder, it is necessary to understand why anyone would use a builder in the first place. Specifically: Bloch recommends using a builder when you have a large number of constructor parameters. That isn't the only reason to use a builder, but I speculate it is the most common. In short the builder is a replacement for those constructor parameters and often the builder is declared in the same class it is building. Thus, the enclosing class already has knowledge of the builder and passing it as constructor argument doesn't change that. That is why a type would be coupled with it's builder.

Why does having a large number of parameters imply you should use a builder? Well, having a large number of parameters is not uncommon in the real world, nor does it violate the single responsibility principle. It also sucks when you have ten String parameters and are trying to remember which ones are which and whether or not it's the fifth or the sixth String that should be null. A builder makes it easier to manage the parameters and it can also do other cool things that you should read the book to find out about.

When do you use a builder that isn't coupled with it's type? Generally when the components of an object are not immediately available and the objects that have those pieces don't need to know about the type you are trying to build or you're adding a builder for a class that you don't have control over.

Answer 4

the product of a creational pattern never needs to know anything about what's creating it.

The Person class doesn't know what's creating it. It only has a constructor with a parameter, so what? The name of the type of the parameter ends with ...Builder which doesn't really force anything. It's just a name after all.

The builder is a glorified¹ configuration object. And a configuration object is really just grouping properties together that belong to each other. If they only belong to each other for the purpose of being passed to the constructor of a class, so be it! Both origin and destination of the StreetMap example are of type Point. Would it be possible to pass the individual coordinates of each point to the map? Sure, but the properties of a Point belong together, plus you can have all kinds of methods on them that help with their construction:

¹The difference is that the builder is not just a plain data object, but allows for these chained setter calls. The Builder is mostly concerned with how to build itself.

Now let's add a little bit of command pattern to the mix, because if you look closely, the builder is actually a command:

1. It encapsulates an action: calling a method of another class
2. It holds the necessary information to perform that action: the values for the parameters of the method

The special part for the builder is that:

1. That method to be called is actually the constructor of a class. Better call it a creational pattern now.
2. The value for the parameter is the builder itself

What is being passed to the Person constructor can build it, but it doesn't necessarily have to. It might be a plain old configuration object or a builder.

Answer 5

No, they're completely wrong and you're absolutely right. That builder model is just silly. It's none of the Person's business where the constructor arguments come from. The builder is just a convenience for users and nothing more.