Reviewing Code Health
Introduction
Welcome to Review for Code Health, our third lesson. We have already reviewed whether a design fits its requirement and traced inputs to check correctness. Now we will look at another aspect of code health: whether a proposal adds complexity that the requirement does not call for. We will use YAGNI, meaning “You Aren’t Gonna Need It,” to review a ticket label change, then follow the evidence from the initial proposal through re-review and approval.
Read the Requirement and Compare with the Proposal
As we did in earlier lessons, we start with the requirement, this time in INITIAL_DIFF.md. It asks us to attach a text label to a ticket. The observable outcome is simple: the ticket has the supplied label. The initial proposal adds three types, so let’s compare them with that outcome.
The proposal provides a plugin interface, a place to register plugins, and an engine to apply them. However, the requirement does not ask us to transform labels or select rules. As you read a proposal, ask: Which parts are needed to produce the required outcome now?
Identify Speculative Abstractions and Their Cost
YAGNI encourages us to avoid building for needs that have not been established. Here, LabelPlugin adds an interface that contributors must understand and test. LabelRegistry adds state and coordination for registering plugins. LabelRuleEngine adds another step that callers must construct and use. Together, these types also create public extension points that the codebase may need to preserve.
No current requirement calls for transformations, colors, permissions, or label lifecycles. Those features may become useful later, but designing for them now means maintaining extra code before we know what constraints they must meet. Our review should explain that practical cost, not simply say that we dislike the design.
Recognize What a Smaller Design Looks Like
Before asking the author for anything, we need a picture of what “smaller” means for this requirement. Count what a caller must touch to attach one label: in the proposal, a plugin, a registry, and a rule engine. Then ask what the requirement actually names. It names a ticket and a text label, so the smallest design lets the ticket hold the label and offers one direct way to attach it.
As reviewers, we do not need to write that replacement for the author. We can request the observable result: store the text directly on the ticket and protect that behavior with one focused test. The author can choose the implementation that meets that request.
