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