Learn

Architecture & pattern guides

Read the idea, build it on a Grid, prove it in a challenge. Short, practical guides — illustrated with RodGrid's own nodes — on system design, design patterns, flow modeling, and how to get the most out of the app.

All articles

Builder

Assemble a complex object one named step at a time, so no caller faces a constructor full of nulls and the same steps can produce different representations.

Nine arguments, three of them null

A travel-booking app shows the customer an itinerary after checkout, and the line that creates it looks like this: new Itinerary(traveller, outbound, inbound, null, hotel, null, null, "EUR", true). Which null is the rental car? What does true switch on? Nobody can tell without opening the class.

The class got there one feature at a time. A trip with a hotel needed one more parameter, then a car another, then insurance another, and each case got its own constructor, longer than the last. This shape has a name, telescoping constructors, and its cost is concrete: meaning is carried by position instead of by name, any optional part that no shorter constructor lets you skip becomes a null someone has to pass, and swapping two arguments of the same type still compiles and quietly produces the wrong trip.

One call per part

The way out is to stop handing over every part at once. A Builder is a separate object that collects the parts one call at a time and hands over the finished object at the end: addTraveller(t), addFlight(outbound), addFlight(inbound), addHotel(h), then getResult(). Each call says what it adds. An optional part is a call you do not make. And the itinerary, which the pattern calls the Product, no longer needs a constructor for every combination of parts.

There is a second gain that is easy to miss. If the builder creates the Product only inside getResult(), no other code ever holds a half-assembled itinerary, and the Product can be made immutable, because it never needs setters for the builder to fill it in.

The same trip as a PDF and as a calendar

Then two requests arrive in the same sprint. Support wants the itinerary as a PDF attached to the confirmation email, and travellers want it in their calendar. The steps have not changed: the traveller, each flight, the hotel. What each step produces has. The PDF needs a page section per flight; the calendar needs one event per flight and one spanning the hotel nights, and has nothing to do with the traveller's loyalty number.

So the steps move into a Builder interface, and each output gets a concrete builder that implements them: PdfItineraryBuilder and CalendarItineraryBuilder. A step that means nothing for one output is an empty implementation there. This is the half of the pattern its definition puts first: separating how an object is constructed from how it is represented, so the same construction process can produce different representations.

Notice where the result comes from. A PDF document and a calendar file share no useful common type, so getResult() usually lives on each concrete builder rather than on the shared interface, and whoever chose the builder asks that builder for its Product.

Who decides the order

The code that walks a booking and calls the steps now exists wherever an itinerary is produced: the checkout page, the email job, the calendar export. The copies drift. One of them calls the totals step before the return flight has been added, and the PDF goes out with a total that leaves out the return fare. Every step worked; they ran in the wrong order.

The Director fixes that by owning the sequence in one place. ItineraryDirector.construct(booking, builder) calls the traveller step, then the flights in date order, then the hotel, then the totals, against whichever builder it is given. It talks only to the Builder interface, so a third output that needs the same steps means a new concrete builder and no change to the Director.

One Director, two representations

The Director calls the same steps in the same order; each concrete builder turns them into its own Product.

NoteThe Director knows the order of steps; the Builder knows how to perform each one.

Builders without a Director

Plenty of codebases never write a Director. The form you will meet most often is the fluent builder: each step returns the builder itself, so the client chains the calls, as in Itinerary.builder().traveller(t).flight(out).flight(back).hotel(h).build(), and build() checks that the required parts are present before it returns anything. Here the client owns the order, and build() is what refuses an incomplete Product. This variant cures telescoping constructors; it usually has a single representation, so the second half of the pattern does not come into play.

Where builders go wrong

Watch outCommon mistake: letting callers invoke build steps in whatever order they like with nothing enforcing a valid sequence, producing half-built or inconsistent products. A Director is one way to own the order. Without one, a build() that checks the parts and refuses an incomplete or inconsistent product is the safeguard, though it catches a bad sequence only after the calls are made.
  • Reusing a builder after getResult(). If the builder keeps the parts it collected, the next itinerary built with it starts with the previous traveller's flights. Either reset the builder when it hands over its result, or use a fresh builder per Product.
  • A builder for an object with three fields. It adds a class and a ceremony and usually saves nothing. A plain constructor does the job, and so do named and default arguments in languages that have them, which remove telescoping constructors on their own.
  • Reaching for Builder when the question is which class to create. Builder is about assembling one object in steps. Letting subclasses decide which concrete class to create is Factory Method, producing a matched family of objects is Abstract Factory, and making many near-identical objects from an expensive one is Prototype.

Two outputs, one Director

Open the Builder Pattern challenge and build the shape from this article: a Port / Interface node that declares the steps, two Builder nodes for two representations of your choice, a Client acting as the Director, and a Product for each builder. Then check two things. The Director's only arrow should go to the interface: if it points at a concrete builder, adding a third representation means editing the Director. And each Product should come out of its own builder, never out of the Director.

Practice this