5.5Code review and interpreting sequence diagrams

Automation is not write-once but the practice of a team changing it safely over time. Two practices for that are this section's theme. One is code review—a mechanism where a third party reads a change before it enters production to check bugs, readability, and security. The other is reading a sequence diagram—the ability to grasp from a diagram in what order and what several components (client, API, auth server) exchange. Both are learned not as memorization but as material for interpreting a given review situation or diagram and judging the next move.

5.5.1Code-review principles and benefits

• The aims of review are early bug detection, readability/maintainability, security, and knowledge sharing. Having a third party read a change before production catches hardcoded plaintext passwords, dangerous deletions, and missed boundary conditions before release. It also strongly prevents siloed knowledge and shares design intent across the team.
• Good review practice: keep PRs small (smaller diffs mean fewer misses), focus on correctness, readability, and security, and comment constructively on the code, not the person. Comments should be specific and grounded, ideally with a suggested fix. Layering human review on top of passing CI automated checks (lint/tests) is efficient.

5.5.2Reading a sequence diagram

• A sequence diagram consists of actors/objects at the top (e.g., Client / Auth Server / API), the lifelines (vertical lines) descending from them, and message arrows connecting them. Time flows top to bottom, and an arrow's direction shows the call direction. A solid arrow = a request (call) and a dashed return arrow = a response is the common notation.
• The knack for reading an API-integration diagram is order and dependency: e.g., "Client -> Auth: request token / Auth -> Client: token (response) / Client -> API: GET (with Bearer token) / API -> Client: 200 + data" reveals the dependency that authentication comes first, data fetch after. If API -> Client: 429 appears midway, the diagram shows the need for rate-limit handling -> wait and retry.

Suppose you are reviewing a colleague's Pull Request. The diff is a Python script calling a Cisco platform's token-auth API, and the attached sequence diagram is: Client -> Auth Server: request token with credentials / Auth Server -> Client: access token (response) / Client -> API: GET /devices (Authorization: Bearer <token>) / API -> Client: 200 OK + device list. The diagram first tells you the order: fetching the token comes first, and fetching the device list depends on it. But reading the code, it calls GET /devices first and fetches the token afterward—the implementation order is the reverse of the diagram's dependency (auth first). This is a "diagram/implementation mismatch"; running it, a request without the auth header is rejected with 401 Unauthorized—a clear bug to flag in review. Further, the diagram's right side depicts a branch for heavy loops, API -> Client: 429 Too Many Requests, yet the code has no wait/retry (backoff) on 429, so it fails wholesale on rate limiting. That too is an implementation gap against the control the diagram assumes. Make review comments specific, grounded, and with a suggested fix: "(1) Per the diagram's dependency, move the token fetch before GET /devices (currently it 401s). (2) Matching the diagram's 429 branch, add a wait-and-retry that respects Retry-After." What to avoid is vague attacks on character or impression like "this code is sloppy"; review should focus on the code's correctness, readability, and security, delivered constructively. The lesson: a sequence diagram can be read as "the spec of the intended order and dependency," and checking whether the implementation matches it is a concrete weapon in review.

5.5.3Section summary

• Code review secures bugs, readability, security, and knowledge sharing before production; keep PRs small and comment on the code, not the person, specifically and with grounds
• A sequence diagram uses actors plus lifelines with time top-to-bottom and arrow direction = call direction (solid request / dashed response); read order and dependency
• Use the diagram as "the spec of intended order/dependency" and check for implementation mismatches (auth deferred causing 401 / missing retry on 429) to decide the next move