Meaning of Implementation

The previous lesson measured that the sets the five axes find are disjoint: the sum of pairwise intersections is 0, and everything each axis finds appears only in that axis. A result follows directly from this but has not yet been tested — if the shares are disjoint, an axis’s contribution must be independent of which axes are already open.

This lesson tests that result, and it tests it on the axis holding the largest single share, the implementation axis. The measurement asks two questions: does the curve change when axes are opened in different orders, and does more people looking at the same axis grow that axis’s share?

What the Implementation Axis Asks

The implementation axis searches for the gap between what the code should do and what it does. This is where it separates from the interface axis: on the interface there were two texts to compare — the signature’s previous and later form. On implementation, one side of the comparison is not text. On one side sits what the body actually does; on the other, what the reader thinks that body should do.

The axis splits into three sub-questions.

Correctness. Does the body do what its name and description say. This question produces the most visible defects, because the code itself is the evidence: a wrong comparison direction, an inverted condition, the wrong variable returned.

Edge case. Is the body correct outside the usual input too. Empty collection, single-element collection, the boundary value itself, division by zero, overflow, concurrent access. The edge-case concept was established in the Software Quality and Testing curriculum’s testing lessons; its review side is measured here.

Complexity. The body’s branch count, nesting depth, and the responsibility it gathers in one place. Naming, function length, and complexity metrics themselves were established in the Clean Code course and are not repeated here. In this lesson these are not a rule list; they are a review finding — something review sees, notes, and asks to be closed. The distinction matters: a rule list applies to a change, a finding points at a specific spot in it.

# taught review-comment example, not executed

correctness    The last element is left out when computing the total; the
               upper bound should be included. Expected value for the same
               input is 15, returned is 10.

edge case      The first element is read when the list is empty. An early
               return for empty input, or explicit handling of the empty
               value, is needed.

complexity     This body has four nested conditions and the third never
               runs outside the first two. Pulling the condition into a
               separate helper function reduces branching to two.

The three notes share a common form: where, what, under what condition. All three point at a spot in the change and name the closing condition. This block is an example and is not run; the lesson’s numbers come only from the measurement block.

Where Correctness’s Oracle Lives

The interface axis had two texts to compare; the implementation axis has no such counterpart. The reader has to derive what the code should do from somewhere, and that place may not be inside the change.

Three sources are available. The change’s description describes intent; when written briefly, the reader tries to infer intent from the body itself, and that is circular — whether the body is correct cannot be settled by looking at the body again. Tests give the expected behavior by example; but if the tests were written in the same change, they may share the same misunderstanding as the body. Documentation gives behavior in words, and if it was not updated along with the change, it describes the old behavior.

That all three sources can be flawed is clear, and this is no coincidence: in the same change, all three come from the same hand. This is why the implementation axis is expensive — the reader has to hold an independent judgment of what the code should do.

This has no counterpart in the measurement, and that absence is deliberate. The setup counts every axis at equal cost: if the axis is open, its class is found. In a real review, the implementation axis is the most expensive per defect and the style axis the cheapest. The table counts defects found, not attention spent; the fact that the two numbers are separate stays open until this course’s last lesson.

Does Contribution Depend on Order

An axis’s marginal contribution is how much the found count rises when that axis is opened. If shares are disjoint, this rise should always equal the size of the class, and the order of opening should change nothing.

This needs to be tested, because intuition says the opposite. In a real review, axes really are opened in sequence: the reading starts somewhere and the reader’s eye shifts as it goes. Intuition says the axis opened first will collect the “easy” defects and less will be left for the ones after. The measurement tests this intuition with two separate orders: one starting from implementation, the other from style.

The Measurement’s Assumptions

• RA16 — The shared setup is unchanged: 600 lines, 12 chunks, 24 defects, attention 12 chunks. There is no unread chunk.
• RA17 — The curve is a single reviewer’s axis set growing step by step. The same change is reread at each step; the reading budget is not exhausted by the step count.
• RA18 — Marginal contribution is that step’s cumulative found minus the previous step’s.
• RA19 — The two orders contain the same five axes, and only their opening order differs; order B is the reverse of order A.
• RA20 — In the second part, reviewers looking at the same axis are identical to one another; the setup includes no share where a second reading catches what the first missed. This simplification is deliberate and ties the measurement’s result to a single variable.
• RA21 — The “reads” column is the number of reviews performed; one person reading twice and two people reading once each are not distinguished in this setup.
• RA22 — The ratio is found divided by 24. The set’s resolution is 1/24 = 0.042.

Measurement

"""Implementation axis: the axis-adding curve and adding people to the same axis.

Part 1 - axes opened in two separate orders: cumulative found and marginal.
Part 2 - implementation axis open, closed, and with many readings.
"""
SEED = 20260815
AXES = ("interface", "implementation", "test", "documentation", "style")
UNWRITTEN = "unwritten requirement"
CLASSES = AXES + (UNWRITTEN,)
ATTENTION = 12
CHUNK = 50


def rng(seed):
    state = seed % 2147483646 + 1

    def draw(n):
        nonlocal state
        state = (state * 48271) % 2147483647
        return state % n
    return draw


def change(lines, defect_count=24, seed=SEED):
    draw, defects = rng(seed), []
    chunk_count = max(1, lines // CHUNK)
    for i in range(defect_count):
        defects.append({"no": i + 1, "class": CLASSES[draw(6)],
                         "chunk": draw(chunk_count)})
    return {"lines": lines, "chunks": chunk_count, "defects": defects}


def review(d, axes, attention=ATTENTION):
    read = set(range(min(attention, d["chunks"])))
    return {k["no"] for k in d["defects"]
            if k["class"] in axes and k["chunk"] in read}


def panel(d, assignments, attention=ATTENTION):
    found = set()
    for axes in assignments:
        found |= review(d, axes, attention)
    return found


def curve(d, order):
    """Axes are opened one at a time; cumulative and marginal at each step."""
    open_axes, rows, previous = set(), [], 0
    for a in order:
        open_axes.add(a)
        n = len(review(d, open_axes))
        rows.append((a, n, n - previous))
        previous = n
    return rows


FULL = set(AXES)
d = change(600)
A = curve(d, ("implementation", "interface", "test", "documentation", "style"))
B = curve(d, ("style", "documentation", "test", "interface", "implementation"))

print(f"{'step':>4s} {'order A':<15s} {'total':>6s} {'marginal':>8s}  "
      f"{'order B':<15s} {'total':>6s} {'marginal':>8s}")
for i, (a, b) in enumerate(zip(A, B), start=1):
    print(f"{i:4d} {a[0]:<15s} {a[1]:6d} {a[2]:8d}  "
          f"{b[0]:<15s} {b[1]:6d} {b[2]:8d}")

print()
FOUR = FULL - {"implementation"}
PANELS = {
    "one reviewer, implementation": [{"implementation"}],
    "three reviewers, implementation": [{"implementation"}] * 3,
    "twelve reviewers, implementation": [{"implementation"}] * 12,
    "one reviewer, four axes": [FOUR],
    "one reviewer, five axes": [FULL],
}
print(f"{'panel':<33s} {'reads':>5s} {'found':>7s} {'missed':>6s} "
      f"{'implementation missed':>22s} {'ratio':>5s}")
for name, assignment in PANELS.items():
    b = panel(d, assignment)
    missed = [k for k in d["defects"] if k["no"] not in b]
    im = sum(1 for k in missed if k["class"] == "implementation")
    print(f"{name:<33s} {len(assignment):5d} {len(b):7d} {len(missed):6d} "
          f"{im:22d} {len(b) / 24:5.3f}")

step order A          total marginal  order B          total marginal
   1 implementation       6        6  style                7        7
   2 interface            9        3  documentation       10        3
   3 test                12        3  test                13        3
   4 documentation       15        3  interface           16        3
   5 style               22        7  implementation      22        6

panel                             reads   found missed  implementation missed ratio
one reviewer, implementation          1       6     18                      0 0.250
three reviewers, implementation       3       6     18                      0 0.250
twelve reviewers, implementation     12       6     18                      0 0.250
one reviewer, four axes               1      16      8                      6 0.667
one reviewer, five axes               1      22      2                      0 0.917

The Curve Is Independent of Order

The top table’s two halves open the same five axes, one starting from implementation, the other from style, and both curves end at 22.

The marginal columns are the measurement’s real result. Implementation is the first axis opened in order A and contributes 6; in order B it is the last axis opened and still contributes 6. Style adds 7 first in B, and 7 last in A. Interface, test, and documentation add 3 in both orders.

An axis’s contribution does not depend on how many axes were opened before it. The intuition that “easy defects get collected first, less is left for later” turns out wrong in this setup, and the reason was measured in the previous lesson: because shares are disjoint, there is no shared pool being drawn down. Every axis brings its own class, and that class cannot already have been collected by any other axis.

Independence has a limit too, and it is a known one. In this lesson attention is not exhausted, because the change is exactly the size of the attention budget. The only case where reading order would matter is when the reading gets cut off before finishing: then, whichever axis was left for later directly becomes an axis never looked at at all. There is no such cutoff in this topic’s measurements.

This has a direct use. A panel’s found count can be computed in advance — without knowing who looked first or which file the reading started from — as the sum of the class sizes of the open axes. Order is not a plan variable; coverage is the only variable that is.

Adding People to the Same Axis

The bottom table’s first three rows give a single number three times: 6.

One reviewer looks at implementation and finds 6. Three reviewers look at the same axis, still 6. Twelve reviewers look at the same axis, still 6. Reading count grew from one to twelve, and defects found grew by 0. The ratio sits at 0.250 in all three rows.

This is the sharpest form of the course’s second claim: adding reviewers does not find defects. “Does not” here is not a figure of speech, it is the measured number — eleven extra readings return zero. The setup achieves this with a simplification: a second reading on the same axis sees what the first one saw. In a real review, a second reading may add a small extra share, but that share’s size never matches what opening a new axis contributes, because the second reading by definition searches within the same class.

This does not mean the second reading serves no purpose; it means it serves a purpose other than finding. The three jobs from the first lesson separate here: a second reading on the same axis does not find defects but spreads knowledge — it becomes that code’s second reader, and the number of people able to look at the implementation axis on later changes grows. A newcomer reading the same axis an experienced person looks at falls into the same class; it is a learning decision.

The distinction sharpens here: if a second reading is a finding decision, it is measurable and its return is 0; if it is a knowledge-spreading decision, this table does not measure it. When the two are swapped for one another, the result comes out wrong. The “let one more person look” decision made after a defect is missed is, by what the number says, uncompensated on the finding side. The decision that does pay off is opening an axis that was not being looked at.

The last two rows give the other end of the same measurement. When the implementation axis is closed, a single reviewer covering the remaining four axes finds 16 defects, and 6 of the 8 missed are in the implementation class. When the axis is reopened, found climbs to 22: the ratio from 0.667 to 0.917. Opening a single axis returns 6 defects; eleven extra readings return 0.

The Separate Weight of the Three Sub-Questions

The measurement gives the implementation class as a single number — 6 — and does not separate its three sub-questions. This is a setup decision; but the separation has a practical consequence that falls outside the table.

A correctness defect has a proof: an input that produces the wrong result can be shown. The finding is not open to debate, and it closes with a single fix.

An edge case defect’s proof is also an input, but whether that input actually occurs can be debated. The finding therefore sometimes closes not with a fix but with a decision: recording that the case is out of scope.

A complexity defect has no input that can be shown. The finding points not at today’s error but at the cost of later changes, and closing it requires a shared criterion. The criterion itself is the Clean Code course’s subject; what is left for review is tying the finding to a specific spot in the change and writing down what counts as closed.

All three are counted in the same class because all three are found by the same axis’s reading. Which round they close in is a separate variable, and it does not enter this topic’s measurements.

Summary

• The implementation axis searches for the gap between what the code should do and what it does, and splits into three sub-questions: correctness, edge case, complexity.
• Complexity here is not a rule list but a review finding: it points at a specific spot in the change and names the closing condition.
• An axis’s marginal contribution is independent of opening order: implementation gives 6 in both orders, style gives 7 in both orders, the remaining three axes add 3 each, and both curves end at 22.
• A panel’s found count is the sum of the class sizes of its open axes; reading order is not a plan variable.
• One, three, and twelve readings on the same axis all find 6 defects; the ratio stays fixed at 0.250. Eleven extra readings return 0, a single new axis returns 6 defects.
• A second reading on the same axis pays off not in finding but in spreading knowledge; when the two are swapped for each other, the “let one more person look” decision goes uncompensated on the finding side.

Next Step

Two axes have been measured so far, and in both, the reason a defect was missed was the same: no one was looking at that axis. But there can be a second reason for a miss — the text the defect sits in was never read at all. There was no such escape in this lesson, because the change was exactly the size of the attention budget. The next lesson separates these two on the test axis: do the defects the test itself carries sit inside chunks that were read, how many times do reviewers reading the same chunk from other axes pass over that defect, and why do they not see it despite passing over it.