Refactoring on Brian Faust

Design Becomes Valuable When the Next Change Arrives

Tue, 01 Dec 2020 00:00:00 +0000

One migration removed four vendor packages. Two payment drivers, their client interfaces, and their factory interfaces did not change; the concrete clients changed substantially.

Two application controllers were less fortunate. They had constructed a vendor connection directly to manage webhooks, so the replacement had to add a small webhook-management role and move the remote protocol behind it.

The same migration produced both results: some earlier seams absorbed the change, while other paths showed exactly where the vendor had leaked through. That tells us more than declaring the design “clean.” A design makes a prediction about future change, and the next real change tells us which parts of that prediction were right.

A Service Class Can Become a Procedural Junk Drawer

Fri, 01 May 2020 00:00:00 +0000

A web controller contained nearly two thousand lines of shipment creation. Moving those lines into a class described as a creation orchestrator sounded like an architectural improvement.

The new class contained nearly two thousand lines of shipment creation.

The first move was still useful. It removed the procedure from the HTTP adapter. What it did not do was make the procedure cohesive. Validation, payment gating, draft persistence, provider booking, tracking, document creation, response mapping, notifications, and indexing still changed inside one file. Service and orchestrator are roles only when the code earns those names. Otherwise they are folders for procedures we no longer want in controllers.

Boolean Parameters Hide Different Operations

Sun, 01 Mar 2020 00:00:00 +0000

This method call is legal:

$exporter->execute($accountId, true, true);

It is also semantically wrong.

The first boolean in the exporter meant “source billing details from the effective payer.” The payload still targeted the original account and kept that account’s operational fields. The second boolean meant “the source’s billing mode is an authoritative instruction.”

An effective-payer export described who pays; it was not allowed to change the original account’s billing mode. The true, true combination therefore had to be neutralized by a later guard.

A Class Name Should Describe a Role

Wed, 01 Jan 2020 00:00:00 +0000

Several classes in one application had almost the same shape. Each extended a connection manager, read named configuration, and delegated object creation to a factory. One managed payment gateways, another rating clients, and another booking clients.

The shared abstraction made their code look alike. Their callers were asking different questions.

Payment callers needed a gateway with a given name. Rating callers sometimes needed to decide which connection matched a shipment. Booking callers selected connections from different rules for creating, collecting, and cancelling, then assembled operation-specific services around the result.

Parallel Implementations Are Not a Replacement Seam

Mon, 01 Apr 2019 00:00:00 +0000

An old shipping integration and its proposed replacement lived beside each other. Both had an interface, a driver, request builders, and tests. From the directory tree, that looked like a seam.

When the replacement was finally made canonical, the change still crossed dozens of files. The old interface disappeared, the new one moved, the canonical driver changed its pickup and shipment flows, and a parallel driver tree was deleted. Follow-up work then corrected a request shape and added serialization tests.

A Characterization Suite Is Scoped to a Change

Fri, 01 Feb 2019 00:00:00 +0000

A booking endpoint had more than thirty characterization cases. They covered successful bookings, validation failures, wallet rules, locks, pending work, email routing, and several provider response shapes.

The next refactor removed one ambient HTTP dependency from the booking services. The suite looked broad enough. It was not broad in the direction of the change.

One service read the global request to persist the original payload. Replacing that read with the existing booking data object would keep ordinary responses green while silently storing normalized values where operators expected the raw input. The suite already protected a test-mode short circuit. It needed a new case for the two representations.