Practice: Write a Design Review Comment

By the end of this lesson, you will be able to...

• Write a short design review comment that separates risk, advice, and requirement.

• Choose might, could, should, and must for different parts of one technical judgment.

• Revise a vague review note into a clearer comment with one visible action.

Idea in one sentence: A good design review comment uses modal verbs to show what may happen, why it matters, and what change the team should or must make.

Core Insight

A design review comment is not only a grammar exercise.

It is a small engineering decision written in public.

Imagine a teammate proposes a new API option:

allow_auto_retry: true

The option looks useful. If a request times out, the client can try again instead of leaving work stuck.

But the change has a risk. A retry might send the same operation twice. If the operation charges a customer, that retry could create duplicate charges.

A weak review comment says:

This is risky and needs fixing.

That sentence is short, but it hides the useful judgment. What is risky? Is the bad result certain? Is the reviewer asking for a suggestion, a requirement, or a blocker?

A clearer comment says:

The client might retry after a timeout and could create duplicate charges.
We should require an idempotency key before enabling automatic retries.
For payment requests, the API must reject a repeated key for the same payment.

The comment is still short. The difference is that each modal has one job.

might -> possible event
could -> possible consequence
should -> recommended design change
must -> hard guardrail

This is the practice for today: write a short design review comment where the modal verbs carry the engineering judgment.

The Small Situation

Use one review scenario.

A team is adding automatic retries to an API client. The client calls three endpoints:

GET /status
POST /payments
POST /emails

Retries are not equally risky for every endpoint.

GET /status only reads state. A retry is usually safe.

POST /payments changes money state. A retry can be dangerous if the first request succeeded but the response was lost.

POST /emails can send the same email twice. That may not lose money, but it can confuse users and support teams.

The naive model is:

Retries are good because they recover from timeouts.

That model is partly true. It breaks because a timeout does not tell you whether the server did nothing.

The server may have received the request, completed the work, and lost the response on the way back.

So the review comment must do two things:

• keep the possible event uncertain;
• make the required control concrete.

Plain meaning:

Say what may happen, what bad result may follow, and what change would reduce the risk.

In this scenario:

The client might retry. The retry could duplicate a side effect. The design should add a protection before the team ships the change.

Technical name:

This is a design review comment with calibrated modal force. The modal verbs show the strength and job of each claim.

Build the Comment in Four Moves

Start with the rough concern:

Automatic retries are risky.

That is a concern, not yet a review comment.

Move 1: name the possible event.

The client might retry after a timeout.

Might is useful because the retry is not guaranteed on every request. It depends on the retry policy and the failure.

Move 2: name the possible consequence.

The client might retry after a timeout and could repeat a payment request.

Could is useful because the repeated request is a possible result, not a certain result.

Move 3: recommend the design change.

We should require an idempotency key before enabling automatic retries.

Should is good review language. It is firm enough to recommend a change, but it does not pretend that every recommendation is already a contract.

Move 4: state the hard guardrail.

For payment requests, the API must reject a repeated key for the same payment.

Must fits the invariant. If this rule is optional, the idempotency key is not a real protection.

Now the full comment is:

The client might retry after a timeout and could repeat a payment request.
We should require an idempotency key before enabling automatic retries.
For payment requests, the API must reject a repeated key for the same payment.

The comment does not sound dramatic. It gives the team a path from risk to action.

A Worked Comment

Now trace the writing process as a small before-and-after.

Input:

Feature: automatic retries for API clients
Concern: timeouts on payment requests
Desired action: require idempotency before enabling retries
Hard rule: repeated payment key must not create a second charge

Transition:

Turn each piece into a sentence with one modal job.

Intermediate state:

The client might retry after a timeout.
The retry could repeat a payment request.
We should require an idempotency key.
The API must reject a repeated key.

That is clear, but a little choppy. Combine the first two sentences because they form one risk path:

The client might retry after a timeout and could repeat a payment request.
We should require an idempotency key before enabling automatic retries.
For payment requests, the API must reject a repeated key for the same payment.

Output:

The reader can now answer four questions:

• What may happen?
• What could that cause?
• What change is recommended?
• Which rule is non-negotiable?

Naive failure contrast:

The retry can duplicate payments, so we must fix it.

That version is less useful. Can duplicate may sound like normal capability instead of uncertainty. Must fix it sounds strong, but it does not name the fix. Strong language without a visible control creates pressure without precision.

How to Choose the Modal

Use this small decision table while you write.

The important habit is not choosing the most formal word. The important habit is matching the modal to the claim.

If the evidence is weak, do not write must.

If the rule is required, do not hide it behind maybe should.

If the comment contains both advice and a hard rule, split them:

We should require an idempotency key before enabling retries.
The payment API must reject a repeated key for the same payment.

So far, the review comment has stayed small. It is small because the grammar is doing focused work.

Check: In this comment, which sentence states a hard requirement?

The client might retry after a timeout and could repeat a payment request.
We should require an idempotency key before enabling automatic retries.
For payment requests, the API must reject a repeated key for the same payment.

Think first, then reveal.

Answer: The third sentence states the hard requirement: the API must reject a repeated key. Must marks the non-negotiable guardrail.

A Second Case: Duplicate Emails

Now change one technical noun and watch the force change.

The team also retries this endpoint:

POST /emails

The risk is different. A duplicate email is annoying and may confuse a user, but it is not the same as a duplicate payment.

A first draft might say:

The client might retry and could send the same email twice, so we must block all automatic retries.

That may be too strong. The possible consequence is real, but the control may not need to be a total ban.

Try a more calibrated comment:

The client might retry after a timeout and could send the same email twice.
We should include a message id so the email service can ignore duplicate send requests.
If the email contains a password reset link, the service must invalidate older links when a new one is sent.

The first sentence keeps the risk visible. The second sentence recommends a design control. The third sentence adds a hard rule only for the sensitive case.

This is the main writing skill. Do not reuse must just because a risk exists. Ask what kind of risk it is.

For a payment, the guardrail may be strict because money state must not change twice.

For a normal notification email, the team may accept the cost of an occasional duplicate if the alternative makes the system much more complex.

For a password reset email, the rule becomes stricter again because security and account access are involved.

Check: Why is must block all automatic retries probably too strong for normal emails?

Think first, then reveal.

Answer: It turns a possible annoyance into a universal requirement. A better comment names a control, such as a message id, and reserves must for the sensitive case where the rule is truly required.

Trade-offs and Limits

Clear modal force improves a review comment because it shows the reader where the uncertainty is and where the requirement is.

The trade-off is that you must slow down for a few seconds. You cannot write one angry sentence and hope the reader finds the design action inside it.

This practice helps when the review concern is real but the team still needs a specific change. It is especially useful for retries, permissions, migrations, rollout plans, API contracts, and incident follow-ups.

It costs a little extra thought. You must decide whether each claim is evidence, possibility, advice, permission, prohibition, or requirement.

It does not solve a weak technical analysis. If the actual risk is wrong, a clear modal chain only makes the wrong idea easier to see.

You can see the boundary when a teammate asks:

Is this a recommendation, or is it a launch blocker?

If the comment cannot answer that question, revise the modal force.

Confusion: Stronger language is always clearer

Why it is tempting:

Design review can feel serious. A writer may use must for every concern because they want the team to pay attention.

Better model:

Strong language is clear only when the requirement is real. Use must for policy, safety, contract, or invariant. Use should for a recommended design change.

Confusion: Polite language means weak technical judgment

Why it is tempting:

Should and could can sound softer than must.

Better model:

Polite does not mean vague. A sentence can be calm and still precise:

We should require an idempotency key before enabling retries.

That sentence gives a direct recommendation without pretending it is already a hard rule.

Confusion: One sentence should contain the whole review

Why it is tempting:

Short comments feel efficient.

Better model:

Short is useful when each sentence has a clear job. If one sentence mixes uncertainty, advice, and requirement, split it.

Practice: Revise a Review Comment

Start with this rough note:

This cache change is dangerous because old prices can happen. We need a fix.

Revise it into a design review comment.

Use this structure:

[possible event] might ...
[possible consequence] could ...
We should ...
If [hard condition], the system must ...

Model answer:

The cache refresh might fail after the deploy and could leave old prices visible.
We should alert when cached prices are older than five minutes.
If stale prices affect checkout totals, the checkout service must block the purchase until prices are refreshed.

Why this works:

• might fail keeps the event uncertain;
• could leave old prices visible names the possible consequence;
• should alert recommends a control;
• must block states the hard guardrail for checkout totals.

Daily Practice Lines:

• The client might retry after a timeout and could repeat a payment request.
• We should require an idempotency key before enabling automatic retries.
• The API must reject a repeated key for the same payment.

Resources

• [ARTICLE] Cambridge Dictionary Grammar: Modals and modality
  • Focus: Compare modal meanings for possibility, obligation, permission, and advice.
• [ARTICLE] Microsoft Writing Style Guide: Be clear and concise
  • Focus: Use short technical sentences where each word has a job.
• [REFERENCE] Google API Improvement Proposals: AIP-155 Request Identification
  • Focus: See a concrete API design reference for request identifiers and repeated requests.

Key Takeaways

• A design review comment should show the path from possible event to possible consequence to recommended action.
• Use might and could for uncertainty, should for a recommendation, and must for a hard guardrail.
• If a comment sounds strong but does not name the control, it is probably pressure, not precision.
• Split advice and requirement when one sentence makes the modal force hard to inspect.