← Back to chrisjmendoza.com

Chapter 3

Invariants and the Canonical Unit

contracts, normalisation, and boundaries

3.1 The most expensive bug in engineering software

In 1999 NASA lost the Mars Climate Orbiter. The spacecraft’s trajectory software received thruster impulse data in pound-force seconds; it expected newton-seconds. Nobody made an arithmetic error. Every individual calculation was correct. The system simply had two units circulating in it, and no single place that said which one was true.

ShaftSchematic has exactly that hazard. The machinists on the client’s shop floor work in inches and think in fractions; marine engineering documents are frequently metric. The app has to accept both, display either, and never confuse them — across ~39,000 lines, eighteen model files, four PDF composers, and two independent rendering paths.

The solution the codebase lands on is the standard one, and it has a name.

3.2 Canonical form

Canonicalisation means: pick one representation, convert everything to it at the moment it enters the system, and use only that representation internally.

ShaftSchematic’s canonical form is the millimetre. Every geometric field in the model is named to say so — lengthMm, diaMm, startFromAftMm, keywayOffsetFromEndMm. The suffix isn’t decoration. It’s the unit assertion carried in the identifier, so that a mistake is visible at every use site, not just at the declaration.

lengthMm is a field name and a tiny act of self-defence.

Note what the diagram does not show: any arrow that carries inches into the core. By design there isn’t one — the sanctioned boundary is exactly two functions, parseToMm on the way in and UnitSystem.fromMillimeters on the way out. Grep for the underlying constant instead of the two function names, though, and the picture gets more interesting — see the Pinch Point below.

3.3 What an invariant is

Here is the precise definition, and it’s worth memorising:

An invariant is a condition that is true before and after every operation on a piece of state, for the entire lifetime of that state.

Not “checked once at startup.” Not “validated on save.” Always true. If you could freeze the program at any instant and inspect memory, the invariant would hold.

“All geometry in the model is in millimetres” is an invariant of ShaftSpec.

Compare that with Body.isValid() from the last chapter. That’s a validation check — a function you call at a moment of your choosing to ask whether a particular condition currently holds. Validation is a question. An invariant is a promise.

The distinction matters because it changes where the work goes:

Look at the cost row. Validation costs you a check everywhere. An invariant costs you a conversion at the border. In a program with two hundred call sites and two borders, the invariant is a hundred times cheaper — which is the whole reason the technique exists.

It’s also, in a very literal sense, what a contractor is being paid for. A client doesn’t ask for an invariant — they state a rule, in plain language, and hand it to you: never store or calculate geometry in inches. Encoding that rule into the shape of the data, so it can’t be forgotten rather than merely checked, is a large part of what the fee is for.

3.4 Preconditions, postconditions, and contracts

An invariant is one of three related promises, and it is worth having all three names because they attach to different moments.

• A precondition is what must be true before a function runs, for the function to be able to do its job. It is the caller’s obligation.
• A postcondition is what the function guarantees afterwards, provided its precondition held. It is the function’s obligation.
• An invariant is what stays true throughout, before and after every operation.

Together they are called design by contract, and the framing is exactly what it sounds like: two parties, each owing the other something specific. If the caller meets the precondition, the function owes the postcondition. If the caller doesn’t, the function owes nothing at all — including a sensible error.

Kotlin gives you three ways to state a contract, and both codebases use all of them:

ShaftViewModelFactory shows the middle one:

require(modelClass.isAssignableFrom(ShaftViewModel::class.java)) {
    "Unsupported ViewModel type: $modelClass"
}

That is a precondition stated in code. require throws IllegalArgumentException — the caller passed something wrong. Its sibling check throws IllegalStateException — this object is in a state where the operation makes no sense. The distinction is about whose fault it is, and choosing correctly is a message to whoever reads the stack trace at two in the morning.

Nobody has ever read a stack trace at a reasonable hour.

Now look at a postcondition stated in prose, from ShaftSpec.withBodyAt:

“Returns a copy with the body at index set to the given geometry, or this unchanged when index is out of range. Length and Ø are clamped to ≥ 0; startMm is kept verbatim (authored positions are sacred — golden rule). Keyway fields, id, and label are untouched.”

Four guarantees about the returned value, none of which the type system can express — ShaftSpec is just ShaftSpec. So they live in KDoc, and WithBodyAtTest is what actually enforces them. That pairing is the practical form design by contract usually takes when the type system can’t express the rule: the contract is written in the doc comment and enforced by the test.

3.5 The conversion itself

Here is the entire unit system:

util/UnitSystem.kt — the entire enum — package line omitted

@kotlinx.serialization.Serializable
enum class UnitSystem(val displayName: String) {
    INCHES("Inches") {
        override fun toMillimeters(value: Double): Double = value * 25.4
        override fun fromMillimeters(value: Double): Double = value / 25.4
    },
    MILLIMETERS("Millimeters") {
        override fun toMillimeters(value: Double): Double = value
        override fun fromMillimeters(value: Double): Double = value
    };

    abstract fun toMillimeters(value: Double): Double
    abstract fun fromMillimeters(value: Double): Double
}

This is worth a slow read, because it’s doing something more sophisticated than it looks.

That fourth point is the good part. Compare with a version that’s easy to reach for first:

// The version this design avoids
fun toMm(value: Double, unit: UnitSystem): Double =
    if (unit == UnitSystem.INCHES) value * 25.4 else value

Functionally identical today. But the if is a conditional on type, and every one you write is a place that must be found and edited when a third case appears. The enum-with-bodies version has zero conditionals: you call unit.toMillimeters(v) and the right implementation runs. This is the Strategy pattern, and the “replace conditional with polymorphism” refactoring is one of the most reliably valuable moves in the catalogue.

3.6 Parsing: turning human text into canonical data

The inbound edge is more interesting than the outbound one, because humans type strange things. The parser has to accept, from a machinist with oily hands on a phone screen:

12        1.25        3/4        15 1/2        4.250"        6 mm

Here it is:

util/Parsing.kt — trimmed

fun parseToMm(raw: String, unit: UnitSystem): Double {
    val v = parseFractionOrDecimal(raw) ?: return 0.0
    return if (unit == UnitSystem.MILLIMETERS) v else v * MM_PER_IN
}

fun parseFractionOrDecimal(raw: String): Double? {
    val t = normalizeNumericText(raw)
    if (t.isEmpty()) return null

    // Mixed fraction: W N/D
    val parts = t.split(' ').filter { it.isNotBlank() }
    if (parts.size == 2 && parts[1].contains('/')) {
        val whole = parts[0].toDoubleOrNull() ?: return null
        val frac = parseSimpleFraction(parts[1]) ?: return null
        return if (whole < 0) whole - frac else whole + frac
    }

    // Simple fraction: N/D
    if (t.contains('/')) return parseSimpleFraction(t)

    return t.toDoubleOrNull()
}

Three structural observations, each of which generalises far beyond this file.

First: it’s a pipeline of narrowing. normalizeNumericText strips commas, trailing unit suffixes, and stray whitespace. Only then does anything try to interpret the result as a number. Separating cleaning from interpreting is why this function is readable at all; a version that handled quotes and fractions in the same pass would be a thicket.

Second: failure is a value, not an exception. parseFractionOrDecimal returns Double? — null for “I couldn’t.” No exception is thrown. The caller decides what “couldn’t” means, and parseToMm decides it means zero. Text arriving from a human is expected to be malformed sometimes; malformed input is not an exceptional circumstance, so it isn’t an exception.

Third, and note this one — the KDoc states a deliberate non-responsibility:

“This keeps parsing neutral: do not clamp negatives or enforce ranges here. Callers (e.g., ViewModel setters) can layer validation if needed.”

That is a separation of concerns decision written down at the point where somebody would otherwise be tempted to violate it. Parsing answers “what number is this text?” Validation answers “is that number allowed here?” They are different questions with different right answers in different contexts, and fusing them produces a parser that can only be used in one place.

One more thing worth noticing before moving on. parseToMm’s own body — return if (unit == UnitSystem.MILLIMETERS) v else v * MM_PER_IN — is exactly the conditional-on-type shape §3.5 named “the version this design avoids.” The sanctioned boundary doesn’t call unit.toMillimeters(v), the strategy object living one file away; it branches instead. With exactly two units, forever, that costs nothing today. But spotting that kind of inconsistency — a pattern named as the thing to avoid two pages back, sitting unremarked in the one function that guards the actual boundary — is exactly the reading skill this book is training.

3.7 Formatting: the outbound edge

Going out is a different problem. LengthFormat.formatInchesSmart() doesn’t just divide by 25.4 — it has to render a number the way a machinist expects to read it:

data class InchFormatOptions(
    val maxDenominator: Int = 16,
    val snapToleranceInches: Double = 1e-4, // ~0.0001" ≈ 0.0025 mm
    val decimalPlaces: Int = 3
)

The logic: try to express the value as a fraction with denominator up to 16; if the value is within 0.0001″ of such a fraction, print the fraction (½, ¾, ⅝ — it even has a Unicode lookup table); otherwise print three decimal places.

Look at snapToleranceInches and think back to the float-equality warning in Chapter 2. A value that entered as 15 1/2 inches became 393.7 mm, was stored as a Float, was maybe involved in arithmetic, and now has to come back out as 15 1/2 and not 15.500. Exact equality would fail. The tolerance is the round-trip guarantee. Without it, typing a fraction and reading it back would produce a decimal, and the app would feel subtly broken to the exact user it’s built for.

3.8 The general pattern: an anti-corruption layer

Step back from units for a moment. The shape you’ve just seen is completely general, and it appears three more times across the two applications:

Every one of these is the same move: the outside world has a representation you don’t control, so you convert it once, at a named place, into a representation you do control, and everything downstream only sees yours.

That named place has a name of its own: an anti-corruption layer. The term comes from Domain-Driven Design and the metaphor is accurate — without it, the outside world’s model leaks inward and corrupts yours. A Postmark that passed raw content://sms cursors around would have Android’s schema, Android’s null rules, and Android’s MMS/SMS ID collisions spread through every screen. Instead it has MessageEntity, and the mess is confined to data/sync/.