Design Before the Pattern Name on Brian Faust

A Design Principle Is a Compressed Failure History

Fri, 01 Jan 2021 00:00:00 +0000

“This violates the single-responsibility principle” is not an explanation. It may be the conclusion of one, but the useful part starts earlier:

Lookup policy, selection policy, and construction policy change for different
reasons. One class owns all three. A lookup change therefore makes selection
tests and construction code part of the review surface.

Once that reasoning exists, “single responsibility” gives it a short name that another engineer can retrieve. Without the reasoning, it is just a respectable label which can justify almost any refactor.

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.

The Type a Caller Receives Defines the Role

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

A payment driver received a client through a factory. The factory promised a five-operation interface. The concrete client had nine additional public methods.

Those extra methods covered token charging, status checks, settlement, cancellation, token management, payment-method lookup, and refund cancellation. None of the callers used them. When the transport was replaced, all nine disappeared along with more than a hundred lines of concrete client code.

The driver did not change, nor did its interface or factory interface. That is what a narrow collaboration buys: not fewer methods everywhere, but a smaller answer to “what may this caller rely on?”

A Method Should Tell You What Changed

Thu, 01 Oct 2020 00:00:00 +0000

A balance reservation could be pending, captured, released, or expired, and only a pending reservation could move to one of the other three states. That gave the system three commands:

capture reservation
release reservation
expire reservation

It did not get one method called updateReservation() with a status argument. The names said which transition the caller intended. The responses included the resulting status, so a caller did not have to guess what a successful request had produced.

Construction Should Not Hide Durable Writes

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

A test called a model factory’s make() method. The model itself was never saved. Two related records were.

The factory computed the model’s default address and account fields by creating real database rows. A test which only needed an in-memory user therefore changed shared state before it reached its first assertion.

A surrounding test transaction usually hid the damage by rolling it back. Tests without that transaction left the rows behind, while another test used TRUNCATE for cleanup, committed the MySQL transaction, and made earlier writes survive the rollback. The method returned an unpersisted object, but its name still gave the wrong account of what had happened.

Global State Makes Local Reasoning Impossible

Sat, 01 Aug 2020 00:00:00 +0000

A repository test created a shipment two days before now, then counted shipments between the start and end of the current month. It passed most days. During the first two days of a month, “two days ago” belonged to the previous month and the count became zero.

Nothing in the test name mentioned a calendar boundary, and nothing in the method signature mentioned time. The same test logic produced a different result because its generated data moved with one more input: the instant at which the test ran. Freezing the clock in the middle of the month stabilized the example. It did not make the dependency local.

Framework Convenience Has a Boundary

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

A model was saved inside a database transaction. Its observer dispatched a queue job. The worker started quickly, looked for the record which described its work, and found nothing.

The record existed in the transaction which dispatched the job, but it was not yet visible to the worker’s database connection. Retained history connects that race to successful wallet payments without a corresponding wallet transaction. The job had been published; the state it needed had not. The framework did exactly what the code asked. The shortcut failed because its lifecycle was smaller than the business operation.

Dependencies Should Be Visible at Construction

Mon, 01 Jun 2020 00:00:00 +0000

This line created a database record:

$user = UserFactory::new()->create([
 'external_id' => 123,
]);

It also performed an HTTP request.

The factory did not mention a client. The model did not accept one. A synchronous observer noticed the external identifier, prepared a profile export, and resolved a connector from global framework state. The connector then looked up a remote account.

In tests without a fake, that lookup reached DNS or the network and retried three times with exponential backoff. Tests which had run in under five seconds took more than thirty. The slow test was annoying, but it was only the visible symptom. A local-looking construction operation had acquired an undeclared remote dependency.

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.

A Primitive Can Hide a Domain Decision

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

Uppercasing a country code looks like normalization:

return mb_strtoupper($input);

It makes fi and FI equal. It also turns finland into FINLAND and leaves FIN looking plausible.

The string is tidier, not safer. The function has changed its shape without answering the domain question: is this a supported country identity in the representation this boundary promises? A primitive becomes expensive when every caller must remember that answer. The reason to introduce a domain type isn’t that strings are unfashionable. It is that the scalar no longer carries enough of the contract.

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.

Invalid State Should Be Difficult to Construct

Sat, 01 Feb 2020 00:00:00 +0000

A wallet reservation held one amount while a booking was in progress. When the booking later reached the billing system, an imported record could contain no price. The reservation knew how much money had been held, but not how that amount divided into net price and VAT. There was no authoritative way to create the final sale from the hold alone; inferring a tax rate would turn a guess into accounting data.

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.