How to Leave a Thorough Design Doc Review Comment in English
Learn the English phrases for reviewing a technical design document thoroughly: questioning assumptions, flagging risks, and proposing alternatives.
A useful design doc comment does more than say “I don’t think this will work” — it names the specific assumption in question, states why it’s a concern, and ideally offers a way to resolve the uncertainty.
Questioning an Assumption
Surface an assumption the document takes for granted.
- “This section assumes the downstream service can handle the increased request volume — has that actually been confirmed with their team?”
- “I want to flag an assumption here: the doc treats this data as always arriving in order, but I don’t think that’s guaranteed upstream.”
- “Is it a hard requirement that this runs synchronously, or is that an assumption we could revisit if it simplifies the design?”
Flagging a Risk or Edge Case
Name specific scenarios the design might not handle.
- “What happens in this design if the third-party API is temporarily unavailable — is there a fallback, or does the whole flow fail?”
- “I don’t see this addressing what happens if two requests for the same resource arrive concurrently — is that considered out of scope?”
- “This seems to assume a single region, which could be a problem if we ever need to run this multi-region — worth noting as a known limitation, at least.”
Proposing an Alternative Approach
Suggest a different direction without dismissing the existing plan outright.
- “Have you considered an event-driven approach here instead of polling? It might reduce the load described in the risks section.”
- “One alternative worth considering: instead of a new service, could this logic live inside the existing service as a new endpoint?”
- “I’m not saying this approach is wrong, but I’d like us to at least compare it against a queue-based design before committing.”
Asking About Scope and Trade-offs
Clarify what the design is explicitly choosing not to solve.
- “Is backward compatibility with the old API version explicitly out of scope here, or just not mentioned yet?”
- “This design trades some latency for simplicity — is that trade-off intentional, and has it been validated against our latency requirements?”
- “What’s the plan for migrating existing data, or is that being handled in a separate document?”
Closing With a Clear Recommendation
Summarize your overall position so the author knows where you stand.
- “Overall I think this is a solid direction — my main concern is the concurrency edge case, which I’d want addressed before implementation starts.”
- “I’m supportive of this approach as long as the fallback behavior for the third-party outage gets documented explicitly.”
- “I don’t think this is ready to move forward yet — the open questions around data migration feel significant enough to resolve first.”
Vocabulary Reference
| Term | Meaning |
|---|---|
| Assumption | A claim treated as true within a design without explicit justification |
| Edge case | An unusual or extreme scenario a design may not have accounted for |
| Fallback | An alternative behavior used when the primary approach fails or is unavailable |
| Out of scope | Explicitly excluded from what a design is intended to address |
| Trade-off | A deliberate choice to accept one cost in exchange for a benefit elsewhere |
Key Takeaways
- Name specific assumptions in a design doc explicitly, rather than vaguely saying something “feels off.”
- Flag edge cases and failure scenarios concretely, asking what the design does in each specific case.
- Propose alternatives as options to compare, not as a dismissal of the existing approach.
- Ask directly about scope boundaries and trade-offs so they’re documented rather than left implicit.
- Close with a clear overall recommendation so the author knows whether their design is ready to proceed.