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. The explanation 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.

Now “single responsibility” gives that recurring pressure a short name. The name helps another engineer retrieve the argument. It does not replace it.

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 did not change. Their client interfaces did not change. Their factory interfaces did not change. The concrete clients changed substantially.

Two application controllers did change. They had constructed a vendor connection directly to manage webhooks. The replacement introduced a small webhook-management role and moved the remote protocol behind it.

The same migration produced both results. Some earlier seams absorbed the change. Other paths exposed exactly where the vendor had leaked through.

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 retained 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. Its interface did not change. Its factory interface did not change.

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. 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.

That state usually disappeared when a surrounding test transaction rolled back. Tests without the transaction trait left it behind. Another test used TRUNCATE for cleanup, which committed the MySQL transaction and made earlier writes survive the rollback.

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. 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.

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. 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.

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.

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.

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 function has changed the string’s shape. It has not answered 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 is not 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 retained 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.