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

Template Method

Write an algorithm's order of steps once in a base class, let subclasses supply the steps that differ, and know what that inheritance costs.

Three syncs into one directory

The review comment on a two-line fix was a question: "Does the HR sync have the same bug?" The fix was to the contractor sync, one of three jobs that fill a company's staff directory. One reads employees from the HR system, one reads contractors from a vendor-management tool, and one reads a spreadsheet a subsidiary uploads every week. Each job does the same things in the same order: connect to its source, fetch the records changed since the last run, map them to the directory's fields, drop the invalid ones, write the rest in batches, and save a checkpoint so the next run knows where to start.

The contractor job had saved its checkpoint before writing. When a write failed halfway, the next run started after records that had never arrived, and a week of new contractors had no directory entry. The fix swapped two lines. The HR job, copied from the contractor job a year earlier, had the same order and the same bug. The spreadsheet job did not, because whoever copied it had already rearranged it for other reasons. Three copies of one procedure had become three procedures, and the order that mattered was written down in three places.

The order lives in the base class

Template Method writes an algorithm's structure once, in a base class, and leaves selected steps to subclasses, so the shape stays the same while the details vary. Here the base class is DirectorySync. Its method run() is the template method: it calls the steps in their fixed order, connect(), fetchChangedSince(checkpoint), toEntry(record) for each record, then validation, batched writes and, only after the last batch succeeds, the checkpoint. Validation, writing and the checkpoint are the same for every source, so the base class implements them. Connecting, fetching and mapping are not, so it declares them abstract, and each source becomes a subclass that supplies those three methods and nothing else.

One run(), three sources

The scheduler starts run() on the base type. Each subclass supplies connect(), fetchChangedSince() and toEntry(); none of them decides when those run.

The calls run the other way from ordinary library code: the subclasses never call the base class's steps in order; the base class calls them. That is inversion of control. The author of SheetSync writes how to read a spreadsheet and never decides when it is read, which is why a new source cannot bring the checkpoint bug back without overriding run() itself: the order is in a method subclasses are not meant to write. Where the language allows it, mark run() so it cannot be overridden (final in Java, simply not virtual in C#); elsewhere that protection is a convention.

Steps a subclass must write, and steps it may

The spreadsheet brought one more difference. Its export still lists people who have left, with a status column, while the HR system and the vendor tool already leave them out. Making "filter the records" abstract would force the other two subclasses to write a method that does nothing. So the base class gives that step a default instead: beforeMap(records) returns the records unchanged, run() calls it between fetching and mapping, and only SheetSync overrides it.

That is the difference between the two kinds of step. A step the base class leaves abstract, which every subclass has to supply, is a primitive operation. A step with a default, often empty, that a subclass may override is a hook. Make a step abstract when every source has to answer it, and a hook when most sources have nothing to add. An abstract step that most subclasses implement as empty is usually a hook in disguise; a hook that every subclass has to override is usually a primitive operation. A hook also beats letting a subclass override a step the base class implements and asking it to call super, which a subclass can forget. Python's unittest uses hooks: setUp() and tearDown() are steps of each test's run that a test class may override, and their defaults do nothing.

What inheritance charges

The variation is the subclass itself, and the price is paid in two places. The first shows up when a second kind of variation arrives. The company's door-badge system needs the same people, so each source now has two destinations, the directory and the badge system. If destinations are varied by subclassing too, the two axes multiply: three sources and two destinations become six subclasses, one per combination.

The second is that subclasses depend on how the base class calls them, not only on which methods it declares. Suppose a maintainer changes run() to map every record once for a dry-run report and once for the real write. A subclass whose toEntry() allocates a new employee number for each record it maps now allocates two, and its code did not change. This is the fragile base class problem: changes to the base class reach every subclass, and writing a safe subclass means knowing when and how often the base class calls each step. Inheritance and abstract classes in general are covered in Inheritance, interfaces and abstract types.

When steps need to vary independently, or change for an object that already exists, move them out of the class hierarchy into objects: the sync job holds a source and a destination and calls them, so the badge system becomes one more destination class instead of three more subclasses. That is Strategy, which varies behaviour through composition where Template Method varies a step through inheritance. Template Method fits when there is one axis of variation and an object keeps its steps for its whole life; which subclass to create can still be picked at runtime, from configuration for example.

Watch outCommon mistake: using Template Method for a step that has to change at runtime for a live object, such as a destination a tenant can switch while its sync job keeps running. In Java and C#, an object's class is fixed when it is created, so the code ends up creating a new sync object, or growing an if inside a step, every time the choice changes; Strategy's composition fits better.

A fourth source

In the Template Method Pattern Challenge, draw the base class as the Template Method node with its template method named, the concrete subclasses as Components, and the step names on the arrows from each subclass, marking which ones are hooks. Then add a fourth source in your head, a partner's API, and check the drawing against it: the new source should be one more subclass with its own steps, and the box that holds the order should not change.

Practice this