design

Design: Getting the Shape Right First

An interface is a promise about how something will be used. Once it has callers, changing it costs a migration, so the cheapest time to get the shape right is now, before anything depends on it.

The disciplines are the same as everywhere else. What changes is that you are choosing rather than repairing, so there is no existing consistency to respect and no cost to doing it well.

Start from the call site

Write the code that will use the thing before writing the thing. A signature that looks reasonable in isolation often reads terribly at the point of use:

report = build(data, True, False, None, 30)

Nothing at that call site says what any argument means. The design problem is visible from the caller and invisible from the definition, which is why the caller is where to start.

The same call with the shape fixed:

report = build(rows, include_inactive=True, timeout=Seconds(30))

Keyword arguments at the boundary, defaults for what is usually right, and a name on every value whose meaning is not obvious from its type.

Parameters

Order by how often they vary. What the caller always supplies goes first; what rarely changes gets a default and goes last.

Make booleans keyword-only. A positional True at a call site is unreadable, and two adjacent booleans are worse: nothing stops a caller transposing them, and nothing detects it afterwards. If a function takes more than one flag, consider whether it is really two functions.

Watch adjacent parameters of the same type. def transfer(src: str, dst: str) accepts its arguments in the wrong order without complaint. Either make them keyword-only or give the two concepts distinct types.

Prefer few parameters to many. More than about four suggests the function is doing several things, or that some of the parameters travel together and want to be one object.

Return shapes

Return the thing, not a status. A function that computes rows should return rows. A count, a boolean or None forces the caller to ask a second question.