Software EngineeringArchive edition7 min read

What a useful code review looks like

Improve correctness and maintainability without turning reviews into contests over style.

Interlocking modular blocks and structured outlines — What a useful code review looks like
Original ARTware computational illustration.

Code review works best as a conversation about a proposed change, supported by concrete evidence. It is not a contest to identify the largest number of improvements. A reviewer who recognizes an important missing input case may provide more value in one paragraph than a reviewer who leaves thirty comments about harmless naming choices. Equally, an apparently tidy patch may conceal a misunderstanding of application behavior. Looking at what the change will do, and asking what evidence supports it, is a more reliable starting point than judging its appearance.

Understand the intended outcome before opening the diff

A useful review begins with a clear description of what is being changed and why. A small bug fix might say that a filter currently includes archived products and should stop doing so. A larger feature might explain a new category of result and how the old workflow continues to behave. This description gives the reviewer a reference point. Without it, a patch can be internally consistent while solving the wrong problem. It also becomes more difficult to tell whether modifications outside the main area of work are incidental cleanup or necessary implementation changes.

The author can make review easier by including a representative example of the previous behavior and the expected new behavior. For the archive filter, a short set of three records with different statuses demonstrates the issue much better than a vague note about correcting selection. A test may already express that example. If it does, point the reviewer to it. This is particularly helpful when the expected behavior depends on a business rule that cannot be inferred from the implementation alone.

Read across the affected behavior

Suppose a change fixes a product list whose source sometimes returns no result. A reviewer sees a new condition that checks for an empty list. That condition looks reasonable in isolation. The next question is what the caller expects in that situation. Should it display a clear empty state, preserve the previous list or indicate that the source was unavailable? Treating a failed retrieval as an ordinary empty list might suppress the very distinction the application needs to explain. The reviewer should follow the affected behavior from the input through to the visible result.

This approach does not require reading the entire project for every edit. Start with the component being changed, its direct callers and the relevant acceptance examples. Expand the inspection when a contract has changed. A new optional parameter might affect callers in different ways; a different interpretation of a stored value might require reviewing older records. The reviewer is looking for hidden assumptions, not just syntax mistakes. That makes the review proportional to the consequences of the change.

Ask what would have happened without the new test

Related reading: Versioning a stable software interface.

A passing test suite is useful evidence, but passing does not automatically mean that the change meets the requirement. An existing suite may know nothing about the modified behavior. The author may add a test that succeeds whether or not the bug is fixed. For a bug correction, consider whether the main test would have failed against the previous implementation. For an intentional change in behavior, check whether the test clearly describes what should happen now, including a representative case that remains unchanged.

The archive filter provides a simple example. A test containing only published records cannot show whether archived records are being excluded. Construct an input that contains both, then compare the expected visible identifiers with the result. Add a separate case in which the source returns no records. If source failure is part of the relevant contract, distinguish it too. There is no need to demand that every patch add dozens of tests. The priority is a small set of examples that can actually disprove an incorrect implementation.

Make comments actionable

A comment that only says a piece of code is bad or confusing is difficult to resolve. The author must either guess what the reviewer means or start a lengthy discussion about an unspecified concern. A more useful comment names the observed problem, describes a condition under which it matters and suggests what evidence or change would resolve it. For instance, a concern about the empty response can explain that a timeout and a valid empty result currently reach the same display path. It can ask for a separate failure outcome or confirmation that the application intentionally treats them alike.

Interlocking modular blocks and structured outlines
ARTware visual study. A complementary computational composition.

Avoid prescribing an unnecessary implementation when the concern is behavioral. The reviewer might see an obvious way to split a function, but the author may know a less disruptive alternative. It is often sufficient to explain that the new branch duplicates a publication rule already owned elsewhere and ask the author to reuse the authoritative rule. Concrete criteria let the author choose an implementation that fits the surrounding design. They also keep the discussion centered on the shared goal rather than on the reviewer's preferred coding habits.

Clarify the severity of each finding

A team can benefit from distinguishing blocking problems from suggestions. An unmet requirement, a plausible correctness defect or an incompatible interface change may prevent acceptance. A possible improvement to an internal name might be useful but need not stop delivery. Reviewers should mark these differences clearly, particularly in a large patch. Otherwise an author may spend more time responding to optional suggestions than addressing the problem that really matters. It is also reasonable to defer legitimate improvement opportunities to separately planned work when they are not necessary to the current change.

Formatting is a special case. A consistent style helps people read code, and simple formatting conventions can be checked automatically. A human reviewer is generally better used to examine an ambiguous contract, a complicated condition or a confusing ownership decision. Style disputes are worth discussing when they materially affect understanding. They are less productive when two forms are equally clear and accepted elsewhere in the project. Ideally, establish a short shared convention so the same argument does not recur in every review.

Review the size and shape of the change itself

Large changes become hard to review when they mix behavior modifications, movement of existing code and cosmetic editing. A reviewer cannot easily tell whether a particular line changed because a product rule was revised or because it moved into a new file. If possible, separate mechanical movement from intentional changes in meaning. An author can also put a clear sequence in the description: an initial commit rearranges the component without changing behavior, followed by a commit that introduces the new condition. The reviewer then knows which comparisons to make.

The goal is not to insist that every substantial feature fit into tiny patches. Some work can only be evaluated as a connected whole. However, even a large feature can state its boundaries and demonstrate its main outcomes. A focused explanation of affected interfaces, data transitions, and deliberately untouched areas makes the complete change much more approachable. The reviewer should call out any surprising modifications to unrelated areas; that gives the author an opportunity to explain a dependency or remove unnecessary edits.

Learn from what the review process misses

Consider a team that repeatedly accepts changes that pass local tests but fail because older content behaves differently. The pattern suggests a missing review question, not necessarily a need for slower reviews in general. Add representative older records to the project's verification examples and ask reviewers to note when the applicable contract changes. If the common defect involves missing values, establish what absence means in the relevant interface. Review findings can reveal gaps in product definitions or shared test material that individual patches cannot fix by themselves.

Turnaround time deserves attention alongside defects. If the same minor issue is repeatedly discussed for several days, the team may need a clearer convention or a way to handle suggested improvements after acceptance. Conversely, if meaningful failures routinely appear after immediate approvals, it may be worth placing more emphasis on behavior-based checks. Observe the kinds of problems the review actually catches and the reasons changes remain pending. Do not use the number of comments as a measure of quality: an important review can be short, and a long review can miss the central issue.

The strongest review relationships depend on clarity and respect for evidence. Reviewers can be direct about genuine risks while acknowledging uncertainty where a requirement is ambiguous. Authors can explain design decisions without treating every question as opposition. When both sides use the intended behavior as a common reference, review becomes part of the engineering process rather than a negotiation over individual preferences. The result is a decision about the change that future maintainers can understand.

Explore the implementation area: Backend development.