Code Walkthrough Phrases

Option C is the strongest: it opens with "This function is responsible for..." which signals a role-first explanation, then describes three specific responsibilities (validate presence, normalise email, return typed result), and names both the success type (ValidatedUser) and the failure type (ValidationError). This is enough for a colleague to understand the contract without reading the implementation.

Key pattern: "This function is responsible for [primary responsibility]: it [action 1], [action 2], and [returns/throws]."

Function explanation phrases:

• "This module is the single source of truth for [concern]."
• "This class is responsible for [responsibility] and nothing else — we kept it focused."
• "The return type is [type] — callers should check for [error condition]."

Option B is the strongest: it uses "The reason we chose X over Y was [specific criterion]", then explains the mechanism (read on every request), quantifies the trade-off (1ms vs 20ms), and contextualises it (at our traffic level). This pattern makes the reasoning auditable — a future engineer can re-evaluate the decision if traffic patterns change.

Key pattern: "The reason we chose [X] over [Y] was [specific criterion] — [quantified or contextualised explanation]."

Technical decision phrases:

• "We considered [alternative] but rejected it because [reason]."
• "This was the right trade-off when we made it — we should revisit if [condition changes]."
• "The ADR for this decision is in [location] if you want the full context."

Option A is the strongest: it opens with "The gotcha here is..." (the standard phrase for a non-obvious hazard), names the specific problem (not idempotent), explains the consequence (double charge), identifies the mitigation (upstream idempotency key), and names the failure scenario (if middleware is bypassed). This gives your colleague everything they need to avoid the trap.

Key pattern: "The gotcha here is that [specific behaviour]. [Consequence]. [Existing mitigation]. [Failure condition]."

Warning phrases in code walkthroughs:

• "Watch out for [condition] — this is the source of most bugs in this module."
• "This is thread-unsafe — we only call it from the main thread to avoid race conditions."
• "The order of operations matters here — if you reverse lines 42 and 43, you'll get a null dereference."

Option D is the strongest: it gives precise line numbers (47-52), names the specific error type being handled (DatabaseConnectionError), describes the retry strategy (3 times, exponential backoff), and explains the fallback (propagate to caller). During a code walkthrough, precise line references prevent your colleague from scanning the whole file.

Key pattern: "If you look at lines [X to Y], that's where we [specific action] — [explanation of why/how]."

Direction phrases:

• "Jump to the [ClassName] class — line [N] is the entry point."
• "The relevant part is the [methodName] method — everything else is infrastructure."
• "Scroll up to the constructor — that's where the dependency injection happens."

Option B is the strongest: it asks for a walk-through (signalling you want a structured narrative, not a one-liner), specifies the scope (from request to response), and clarifies what you're particularly interested in (data transformations at each step). This structured question helps your colleague give a focused, useful explanation rather than an unfocused tour.

Key pattern: "Could you walk me through [specific flow] from [start] to [end]? I'm particularly interested in [aspect]."

Request-for-explanation phrases:

• "Walk me through how this handles the edge case where [condition]."
• "Can you show me where [concern] is handled?"
• "I'd love to understand the design decision behind [specific choice]."
• "What would happen if [unexpected input] was passed here?"