apud machinam · mmxxvi

ETHICA·DEV

Ordine geometrico demonstrata,
or, A Treatise on the Conduct of Developers

in six parts, with marginalia, manicules, and demonstrations

PARS PRIMA

Of Definitions

In which the terms by which a developer may be judged are first given names.

i.i.

DEFINITIO I. — By code I understand that which, when read, can be made to act.

EXPLICATIO

The definition is offered prior to all argument, that we may afterward say *code* without confusion. Whatsoever is written and afterward executed by a machine — be it Lisp, Latin, or the silent grammar of a configuration file — falls under this name. That which is written and *cannot* be made to act is not code but commentary, and is governed by the second definition (def. i.ii.).

i.ii.

DEFINITIO II. — By commentary I understand that which is written beside the code, by which the reader is informed of the writer's intention.

Commentary is therefore a *promise* between two readers — the writer of yesterday and the reader of tomorrow — and is bound by all the obligations of a promise. We shall return to it in Prop. iii.ii.

i.iii.

DEFINITIO III. — By a name I understand a sign which truthfully indicates that to which it is attached.

A name which misleads is, by this definition, no name; it is a misnomer, and it acts upon the reader as a false witness. Whether a name be well- or ill-given is therefore not a matter of taste but of correspondence between the sign and the thing signified, as a triangle is well- or ill-inscribed in its circle (fig. i.).

PARS SECUNDA

Of Axioms

That which, being self-evident to the practising developer, requires no proof.

ii.i.

AXIOMA I. — Every system runs in service of some reader, present or future.

This is granted without demonstration; for a system that is read by no one — neither by another developer, nor by the future self of its author, nor by a machine that translates it — has, in the proper sense, no existence as code, but only as inert characters upon a disk.

ii.ii.

AXIOMA II. — The reader's attention is finite, and the demands made upon it are cumulative.

Every name, every nesting, every silent precondition imposes a small tax upon attention; the sum of these is what is felt as complexity. From this axiom many later propositions will follow (esp. iv.iii.).

ii.iii.

AXIOMA III. — Every change is paid for at least twice: once when it is made, and again each time it is read.

The first cost falls upon the writer; the second, distributed across the lifetime of the system, falls upon every reader thereafter. This axiom is the engine of Pars iv.

PARS TERTIA

Of Honesty in the Code

Wherein the names, types, and signatures of the system are required to keep faith with the reader.

iii.i.

PROPOSITIO I. — That which is well-named cannot be cruel.

DEMONSTRATIO

By def. iii., a name is a sign which truthfully indicates that to which it is attached. Cruelty in code is not, properly speaking, a matter of intention, but of the disjunction between what the reader is led to expect and what the program in fact does. By def. iii., a true name eliminates that disjunction at its source. Therefore the well-named function, class, or variable cannot mislead the reader; and that which cannot mislead cannot, in the relevant sense, be cruel. Q.E.D.

iii.ii.

PROPOSITIO II. — A function which lies in its return type lies also to its caller.

DEMONSTRATIO

By def. iii., a sign which fails to indicate truthfully is no name. The return type of a function is a sign affixed by the writer to the result of the function; if the result does not, in some execution, conform to that sign — if a function declared to return User may in fact return null without warning — the sign is, by def. iii., no name, and the writer's contract with the caller is, by ax. ii., dishonoured. Therefore the lie in the type is identical with a lie to the caller. Q.E.D.

function find(id: string): User { ... }
// — but this function may return null.
// the type lies; therefore the function lies.
iii.iii.

PROPOSITIO III. — The error which is silently swallowed becomes, by virtue of its silence, the property of every later reader.

DEMONSTRATIO

By ax. ii., the reader's attention is finite; what is not surfaced cannot be attended to. By ax. iii., every change is paid for again at each reading. An error caught and discarded without record imposes upon every subsequent reader the labour of inferring its absence — a labour they cannot know they are performing. Hence the silent catch is not an act of mercy upon the writer's day, but a tax levied upon all who come after. Q.E.D.

PARS QUARTA

Of the Care Owed to the Future Reader

That the developer's first reader is, in nearly every case, a stranger — and most often the developer themselves, six months hence.

iv.i.

PROPOSITIO IV. — The developer who writes only for the present moment writes against themselves.

DEMONSTRATIO

By ax. iii., every change is paid for at least twice. The writer who attends only to the first payment leaves the second to be discharged by another — typically by themselves, in another month, having forgotten the first. By ax. ii., the reader's attention is finite and cumulative; therefore the cost compounds. Hence the present-only writer is not generous to themselves but profligate, in the strict sense of the word. Q.E.D.

iv.ii.

PROPOSITIO V. — The well-placed comment is a gift; the misplaced comment, a debt.

DEMONSTRATIO

By def. ii., a commentary is a promise from the writer of yesterday to the reader of tomorrow. A promise kept enriches the recipient; a promise broken impoverishes them by the cost of discovering the breach. The comment which states what the code already says is the former made trivial; the comment which states what the code used to do is the latter made venomous. Q.E.D.

iv.iii.

PROPOSITIO VI. — Brevity, when it obscures, is no virtue; verbosity, when it clarifies, is no vice.

DEMONSTRATIO

By ax. ii., the reader's attention is taxed by every nesting, every name, every silent assumption. Both excessive brevity and excessive verbosity raise the tax — the first by compressing several taxes into a single character, the second by spreading one tax across many. The right measure is whichever permits the next reader to discharge the line in a single breath. The matter is one of fitness to the reader, not of taste in the writer. Q.E.D.

PARS QUINTA

Of Form and Order in the System

Wherein the architecture of a system is shewn to be a moral artefact, and not merely a technical one.

v.i.

PROPOSITIO VII. — The boundary which is well-drawn is itself a kindness.

DEMONSTRATIO

By ax. ii., the reader holds in attention only what the system requires of them. A well-drawn boundary — a module, a function, an interface — releases the reader from holding what lies beyond it. To draw the boundary well is therefore to give the reader back a portion of their attention; to draw it badly is to confiscate that portion under another name. Q.E.D.

v.ii.

PROPOSITIO VIII. — The interface which conceals what its caller must know is a fortification turned inwards.

DEMONSTRATIO

By def. iii., a name is a sign that indicates truthfully. An interface which advertises one signature and requires the caller to know another, undeclared signature in order to use it correctly, is by def. iii. no interface but a misnomer. Such a structure does not protect its callers; it ensnares them. The remedy is in Prop. v.iii. Q.E.D.

v.iii.

PROPOSITIO IX. — That which can be deleted without grief was not part of the system.

DEMONSTRATIO

By def. i., code is that which, when read, can be made to act. That which is no longer read, is not made to act, and excites no protest upon its removal, has by def. i. ceased to be code; it is residue. The continued presence of residue is paid for in confused readings (ax. ii.) and in changes that need not have been made (ax. iii.). Therefore its removal is owed to the system as much as its writing was. Q.E.D.

PARS SEXTA — et finis

Of the Free Developer

That toward which the entire treatise has tended; the conclusion in which the argument completes itself.

vi.i.

PROPOSITIO X. — The free developer, who acts from understanding, leaves their successor a tractable codebase.

DEMONSTRATIO

By the preceding propositions: the free developer names well (i.iii., iii.i.), keeps faith with the type (iii.ii.), refuses the silent error (iii.iii.), writes for the future reader (iv.i.), holds the comment as a promise (iv.ii.), measures their words by fitness (iv.iii.), draws boundaries that release attention (v.i.), refuses the inward fortification (v.ii.), and removes what no longer acts (v.iii.). One who acts thus does not labour for the successor as for a stranger; they labour with the successor, who is themselves at another date. The codebase that results is tractable not by accident but by demonstration. Q.E.D.

Finis. — Compositum apud machinam, anno mmxxvi.