Tarin Gamberini

A software engineer and a passionate java programmer

A more communicative Builder

The Builder pattern [1] is a good choice when designing classes whose constructors have more than a handful of parameters, not only because is less error prone in case of identically typed parameter, but also because it is more readable from the client [2]. For example, instead of instantiating an Application object with its constructor:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
public class Client {
    ...
        Person legalRepresentative = getLegalRepresentative();
        Company beneficiary = getBeneficiary();
        Person notary = getNotary();
        Person localOfficial = getOfficial();
        Company centralOffice = getOffice();

        Application application = new Application(
                legalRepresentative,
                beneficiary,
                notary,
                localOfficial,
                centralOffice);
    ...
}

we could use an ApplicationBuilder or, if the builder is an Application inner class, an Application.Builder as:

1
2
3
4
5
6
7
Application application = new Application.Builder().
        setLegalRepresentative().
        setBeneficiary(beneficiary).
        setNotary(notary).
        setOfficial(localOfficial).
        setOffice(centralOffice).
        build();

What I don’t like

When I see new Application.Builder(). ... .build() I understand without any problem. But a monkey shout in my head something like: «Hei! if you do “new” what is that ending “build”?».

I know the new purpose is letting me instantiating the Builder, whose setter return a Builder in order to allow a fluent interface style, and the ending build() purpose is returning a new instance of the Application object. But to shut up the monkey I want to remove the new.

Of course some method should instantiate the Builder therefore I use a static factory method [2] which name is exactly setLegalRepresentative():

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
public class Application {
    ...
    public static ApplicationBuilder setLegalRepresentative(Person legalRepresentative) {
        return new ApplicationBuilder().setLegalRepresentative(legalRepresentative);
    }
}

public class Client {
    ...
        Application application = Application.
                setLegalRepresentative().
                setBeneficiary(beneficiary).
                setNotary(notary).
                setOfficial(localOfficial).
                setOffice(centralOffice).
                build();
    ...
}

While I’m used to new Application.Builder(). ... .build() the syntax Application. ... .build() doesn’t make me think to the Builder pattern or, however, to something familiar. I prefer using one of the more used naming convention for static factory methods, therefore I change from build to newInstance:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
public class Application {
    ...
    public static ApplicationBuilder setLegalRepresentative(Person legalRepresentative) {
        return new ApplicationBuilder().setLegalRepresentative(legalRepresentative);
    }
}

public class ApplicationBuilder {
    ...
    public Application newInstance() {
        return new Application(legalRepresentative, beneficiary, notary, official, office);
    }
}


public class Client {
    ...
        Application application = Application.
                setLegalRepresentative().
                setBeneficiary(beneficiary).
                setNotary(notary).
                setOfficial(localOfficial).
                setOffice(centralOffice).
                newInstance();
    ...
}

I find Application. ... .newInstance() as clear as Singleton.getInstance(), even if the ending newInstance() method isn’t a static factory method itself! The fact that under the cover of the static factory method setLegalRepresentative there is a Builder is irrelevant to me in order to get a new instance of Application.

Get rid of set set set

The set verb is a JavaBeans convention but it conveys very poor meaning. Of course you can take care of that meaning writing javadoc comments but, from the developer experience, they are a step after the method name.

In order to get a more communicative name I use verb phrase method names [3]:

1
2
3
4
5
6
7
8
9
10
11
public class Client {
    ...
        Application application = Application.
                signedByLegalRepresentative(legalRepresentative).
                onBehalfOfTheBeneficiary(beneficiary).
                signedByTheNotary(notary).
                submittedFromTheOfficial(localOfficial).
                submittedToTheOffice(centralOffice).
                newInstance();
    ...
}

I suggest using the same verbs business people use to communicate each other, because in this way developers using your builder will learn business domain language and concepts [4].

Comments

Adding a static factory method like static ApplicationBuilder signedByLegalRepresentative(...), even if doesn’t interfere with the JavaBeans naming convention for the legalRepresentative field setter, it isn’t always practical.

In fact in the implementation above this method is not only used as a setter but, more importantly, it is the factory of the builder. What would happen if the field legalRepresentative was optional? “Polluting” the Application class with as much factory methods as many optional fields, even if workable, is impractical.

Clearly we could still use a static method to only build the builder, and not to set the filed, but which name it should have? build()? I think that variants like:

  • Application.build(). ... .newInstance()
  • Application.newInstance(). ... .build()
  • Application.foo(). ... .bar()

can’t be read as smoothly as Application. ... .newInstance().

Bibliography

[1] E. Gamma, R. Helm, R. Johnson, J. Vlissides, and G. Booch, Design Patterns: Elements of Reusable Object-Oriented Software, 1 edition. Addison-Wesley Professional, 1994. ^

[2] J. Bloch, Effective Java, 2 edition. Addison-Wesley Professional, 2008. pag. 5 ^, pag. 6 ^

[3] R. C. Martin, Clean Code: A Handbook of Agile Software Craftsmanship, 1 edition. Upper Saddle River, NJ: Prentice Hall, 2008. Pag. 25 ^

[4] E. Evans, Domain-Driven Design: Tackling Complexity in the Heart of Software, 1 edition. Boston: Addison-Wesley Professional, 2003. ^

Post a comment

A comment is submitted by an ordinary e-mail. Your e-mail address will not be published or broadcast.

This blog is moderated, therefore some comments might not be published. Comments are usually approved by the moderator in one/three days.