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