1. LandOffer
  2. Blog
  3. All articles
  4. Code Review Comments That Explain the Problem and Leave Room for Discussion

Workplace Communication

Code Review Comments That Explain the Problem and Leave Room for Discussion

Use tested Python behavior and complete fictional review threads to separate a required correction, an optional design change, and a nonblocking naming preference.

9 min readLandOffer team

Write a code review comment by identifying the specific problem, explaining why it matters, and stating whether the author must address it in this change. Offer enough evidence or context to make the concern testable, then leave room for the author to explain a constraint or propose a different fix. A required correction, a design suggestion, and a personal preference should not arrive as three identical demands.

This guide from LandOffer.ai uses an original, isolated Python example and fictional review conversations. We actually ran the code checks described below; the people, repository contract, and threads are invented. No comment was posted to a real pull request, and no employer code or private review was accessed.

A negative batch-size example produces an empty result, with a reviewer annotation explaining the problem and inviting discussion. Original editorial illustration.

Put the concern beside the relevant code

Begin with the behavior or constraint you are reviewing, not a judgment about the person who wrote it. “This accepts a negative batch size and returns an empty result” gives the author a concrete starting point. “You did not think about validation” assumes a mental state and provides less useful information.

Google's guidance on writing review comments recommends explaining reasoning, discussing code rather than the developer, and making comment severity visible. It also recognizes that reviewers should balance pointing out a problem with giving direct guidance. These are Google's published engineering practices, not a mandatory labeling scheme for every team.

A useful comment can answer four questions in a few sentences: where is the issue, what happens, why is that a problem here, and what response is needed? Include a small reproduction or relevant requirement when it resolves uncertainty. State whether you need an explanation or a correction before the change can proceed; the author should not have to infer that from your tone.

Use the review location deliberately. GitHub's commenting documentation distinguishes general discussion from comments on a file or specific lines. Keep a local implementation concern near the relevant change; use a summary for the overall assessment. The useful principle is context, not the number of comments you can leave.

Read the change description and nearby code before treating an unfamiliar choice as a mistake. A condition may enforce a requirement that is not obvious from one line. If you lack that context, ask a question and name the uncertainty: “Does this helper allow negative sizes, or should callers receive an error?” Once the requirement and behavior are established, replace the uncertain question with a precise concern if one remains.

Avoid scattering the same issue across several lines. Point to one representative location, describe the affected pattern, and ask the author to check related cases. If a different occurrence has a different consequence, explain that difference. This makes the review easier to address without pretending that a repeated observation is several independent defects. Read your comments together before submitting them so that the requested actions are consistent.

Establish the contract before calling something a bug

Our fictional change adds a helper that divides a list into batches. The invented contract requires a positive integer batch size, explicitly excludes booleans, and returns a list of batches. That contract is a teaching assumption, not a universal batching standard.

The first implementation is short:

def batches(items, batch_size):
    return [list(items[i:i + batch_size])
            for i in range(0, len(items), batch_size)]

In our actual local Python 3.12.14 check, batches([1, 2, 3], -2) returned []. Zero raised ValueError, but the negative value did not. True produced single-item batches rather than being rejected. Those two behaviors violate the stipulated contract; they do not establish that this implementation is wrong for every possible caller or specification.

If you and the author disagree about expected behavior, identify the requirement before arguing about syntax. A reproduction establishes what happened in that environment. The contract establishes whether that behavior needs to change. Neither should be replaced by “this is obviously wrong.”

Completed thread: a required correction with evidence

The following reviewer, Morgan, and author, Imani, are fictional. The input and outputs come from the local example, while their conversation illustrates how to reason about them.

Morgan — Required: The contract says a nonpositive batch size must be rejected. With [1, 2, 3] and -2, this implementation returns [], so a caller could mistake invalid configuration for an empty workload. Zero already raises an exception, but it does not cover this negative case. Could you add explicit validation and a regression check? The contract also excludes booleans, which this implementation currently accepts.

Imani: I assumed the range step would reject invalid sizes because zero already fails. Do we need a separate guard if configuration is validated before this helper is called?

Morgan: For this example, the helper's stated contract includes that boundary; upstream validation does not change it. I reproduced negative and boolean inputs directly. If we want validation to belong only to the caller, we should change the contract and review the callers explicitly. My requested fix is rejection at this boundary, not a particular spelling of the guard.

Imani: I added the boundary checks below, retained the list return type, and reran the example checks. Negative and boolean values are now rejected. I also documented the accepted argument in the function docstring.

Morgan — Resolution: The new checks address the stated cases and the contract remains clear in the code. This thread is resolved for the example; the overall review still needs its normal assessment.

The resulting implementation is:

def batches(items, batch_size):
    """Return list batches; batch_size must be a positive int, not bool."""
    if type(batch_size) is not int:
        raise TypeError("batch_size must be an integer, not bool")
    if batch_size <= 0:
        raise ValueError("batch_size must be positive")
    return [list(items[i:i + batch_size])
            for i in range(0, len(items), batch_size)]

The exact-type check deliberately rejects booleans under this example's contract. It is not a recommendation to reject subclasses in every library. If a real helper supports a broader numeric protocol, its validation design and tests would need to reflect that different requirement.

Our saved harness ran eleven checks covering ordinary, empty, exact, single-item and oversized batches; zero, negative, float, boolean and string sizes; and independence of the outer batch lists from the original list. The first implementation passed nine of eleven; the corrected one passed eleven. The failures were specifically the negative and boolean cases, not an unspecified improvement in quality. These are bounded checks of this small helper, not a production benchmark or proof of complete correctness. They do not establish deep copying of contained objects, performance, or behavior under concurrency.

Completed design discussion: keep a valid alternative open

A design suggestion needs its trade-off as well as its proposed implementation. Returning an iterator could avoid building the complete outer list immediately, but it also changes how callers use the result. Do not turn that observation into a measured memory-saving claim without testing the relevant workload.

Morgan — Optional design suggestion: Would an iterator fit the expected workload better than returning all batches at once? It could change when batches are constructed. I am not treating this as a required correction; the current contract returns a list. Have we considered the callers' need to inspect the result more than once?

Imani: The representative consumer in this example calls len(grouped) and indexes the first batch. An iterator changes that interface. I prefer to retain the list for this change and discuss streaming separately if we identify a workload that needs it.

Morgan — Resolution: Agreed: keep the list under the current contract. The possible streaming direction is not required here, and we have not measured its performance. I will not hold this change for that redesign.

We separately ran a generator candidate in the local fixture and confirmed that calling len() on it raises TypeError. That establishes the narrow compatibility concern in the example. It does not prove that iterators are generally inferior, that every caller indexes results, or that a streaming interface could not be designed correctly.

Google's standard of code review emphasizes technical reasoning over personal preferences and balancing improvement with progress. Use the applicable design principles and repository conventions to decide whether a suggestion is necessary. A valid alternative can remain unchosen without making the author uncooperative.

Three resolved review discussions distinguish required size validation, an optional iterator alternative, and a nonblocking naming preference.

Completed preference thread: withdraw the unnecessary demand

Some comments concern taste. A long list of unexplained preferences can make an author feel that the target keeps moving. If no rule or meaningful readability issue requires the change, say that the preference is nonblocking and be willing to accept the existing choice. A label such as “nit” does not have an identical meaning on every team; explicitly state what action you expect.

Morgan — Personal preference, nonblocking: I initially preferred group_size to batch_size. I cannot point to a repository rule or a difference in meaning that requires the rename. Keep the existing name if it matches the surrounding batching terminology.

Imani: I will keep batch_size so the argument matches the helper's name and docstring.

Morgan — Resolution: That is consistent. No rename is required, and there is no follow-up task from this preference.

This thread closes without a code change. That can be a correct result. The author has answered the question, the reviewer has withdrawn the unnecessary demand, and future readers can see why the wording stayed. A review should not create busywork merely to give every comment a visible diff.

These labels also help the author allocate attention. The validation concern changes behavior under the agreed contract and needs a correction. The iterator suggestion asks whether another interface is useful, but does not override the existing one. The naming preference identifies no rule requiring action. If you later discover that a supposedly optional point affects a requirement, explain that new evidence and change the label; do not quietly treat an optional suggestion as an unannounced blocker.

Use specificity for praise too. “The regression cases cover the negative and boolean values discussed above” reinforces a concrete improvement. “Great job” may be friendly, but it does not explain which behavior or decision should be repeated. Recognition need not exaggerate the coverage the checks provide.

Keep the explanation where future readers need it

Google's author guidance on handling comments recommends clarifying the code or adding appropriate code comments rather than leaving necessary understanding only in the review tool. In this example, the argument boundary belongs in the docstring and the regression cases remain in the test fixture. The thread explains the decision but is not the sole definition of the contract.

When an explanation changes your understanding, acknowledge it and revise the comment's status. If the discussion becomes circular, summarize the actual unresolved choice, the requirement each approach serves, and who can decide it. Bring in the appropriate maintainer or technical decision-maker. Record any decision reached outside the thread. Do not let an old question remain ambiguously blocking after the concern has changed.

In these fictional examples, resolving a discussion records that the participants addressed that concern. It does not establish that tests passed, the whole review was approved, or the change merged. Those are separate conclusions requiring their own evidence. The resolutions above record reasoning; no repository action occurred.

Before submitting your next review, revise one comment to include the observed problem, its consequence under the actual contract, and the required response. If you have not run a suspected reproduction, label it as a question rather than claiming an observed failure. Separate optional design work and personal preferences from corrections that matter now. This guide is from LandOffer.ai; the practical goal is a review the author can understand, answer, and close without guessing what you meant.

Sources and Further Reading