Unified Diffs, Code Review and Sequence Diagrams

What it is

This page covers three reading skills: unified diffs, code review and sequence diagrams.

A unified diff shows what changed in a file. A code review checks a change before it is merged. A sequence diagram shows calls between systems over time.

All three help you understand a change without running it. They are also how teams discuss and approve work.

A diff answers what changed, a review answers whether it should, and a sequence diagram answers who talks to whom and in what order.

How it works

Each skill follows a fixed format, so learn the format and read it in order.

Reading a unified diff

A unified diff compares two versions of a file. Git produces it with git diff.

diff --git a/app.py b/app.py
--- a/app.py
+++ b/app.py
@@ -1,6 +1,7 @@
 import requests
 
-TIMEOUT = 5
+TIMEOUT = 10
+RETRIES = 3
 
 def get_devices(url):
     return requests.get(url, timeout=TIMEOUT)

In this example the timeout changed from 5 to 10, and a new RETRIES setting was added. The old hunk has 6 lines and the new one has 7, so the net change is one extra line.

A file can have several hunks, each with its own @@ header. A new file shows --- /dev/null, and a deleted file shows +++ /dev/null.

A changed line appears as a pair: the old line with a minus, then the new line with a plus. A plus line alone is a pure addition, and a minus line alone is a pure removal.

The same idea for configuration

Diffs work for any text, such as a device configuration or a YAML file.

--- running_before.cfg
+++ running_after.cfg
@@ -4,2 +4,3 @@
 interface GigabitEthernet1
- description WAN
+ description WAN to ISP
+ no shutdown

You can read it as: the description changed, and the interface was enabled. Automation tools use diffs to show a planned change before they apply it.

Code review

In a code review, someone other than the author reads a change and gives feedback before it joins the main branch. It is usually done through a pull request or a merge request.

Benefits

• Fewer defects. A second reader sees mistakes that the author missed.
• Shared knowledge. More people understand the code, which cuts the risk when someone leaves.
• Consistency. Reviews keep style and design aligned.
• Security. A reviewer can spot unsafe handling of input or secrets.
• Learning. Juniors learn from the comments, and seniors see new ideas.

Principles of a good review

• Keep changes small, so they can be reviewed well.
• Run automated checks first, such as tests and linters, so humans focus on design and logic.
• Review the code and not the person. Comments are specific, polite and useful.
• Check correctness, readability, tests, error handling and security.
• Decide clearly: approve, request changes, or comment.
• Respond to every comment, and re-review after changes.

In automation, the same process protects the network. A reviewed playbook or template is less likely to cause an outage.

Reading a sequence diagram

A sequence diagram shows the participants as vertical lines, and the messages between them as horizontal arrows. Time runs from top to bottom.

Client           Auth API         Device API
  |  POST /token     |                |
  |----------------->|                |
  |  200 and token   |                |
  |<-----------------|                |
  |  GET /devices with token          |
  |---------------------------------->|
  |  200 and device list              |
  |<----------------------------------|

To read it, follow these steps:

1. Name the participants across the top.
2. Read the arrows from the top downward. A solid arrow to the right is a request.
3. A returning arrow is the reply, with its status code or data.
4. Note which data is passed on, such as the token that is used in the second request.

Here the client first logs in and gets a token. It then uses the token to request the device list. The order matters, because the second call would fail without the token.

Frames in a sequence diagram

Diagrams can show loops, alternatives and optional steps with a labelled box.

loop until the task is done
  Client  ->  API : GET /tasks/ID
  API     ->  Client : 200 with progress
alt task finished
  Client  ->  API : GET /results/ID
end

A loop repeats the steps, and alt gives alternative paths. An asynchronous flow often shows a 202 reply, then a loop that polls.