Chapter 4 · Design and Code
Code Review, Version Control and Team Workflow
- Page 14 of 18
- 16 min read
When Farhan worked alone on the first prototype, he could change any file at any time. Now four people change ClinicQueue every day. Without shared habits, Aiko's change overwrites Farhan's, a half-finished feature reaches the clinic, and nobody remembers why a line was changed. Team workflow is the set of habits that prevent this: every change lives on its own branch, another person reviews it, and the main code is always in a state you could release.
On the previous page, Writing Maintainable Code, you made one function easier to read and change. This page is about how a team gets such changes from one laptop into the shared product safely. The Git commands themselves are taught in Git, APIs and Backend for AI: Beginner; here the focus is on the team practices around them. All names, issue numbers and branch names are invented.
What you will learn
- Why teams review code, and what a reviewer actually checks.
- How to give and receive review comments respectfully, and why small pull requests get better reviews.
- A simple branching workflow: feature branches, pull requests, and a main branch that stays releasable.
- How commit messages, a Definition of Done and an issue tracker connect the work.
- What pair programming is and when it is worth it.
Why code review
A code review is a check of a change by at least one person who did not write it, before the change joins the shared code. Teams do it for three main reasons:
- Finding defects early. A second reader notices the missing check, the wrong boundary, the case the author did not think of. Fixing it before release is cheaper than fixing it after; the ISTQB testing syllabus lists the same idea as one of its principles, "Early testing saves time and money", and a review is one of the earliest checks there is.
- Sharing knowledge. After Aiko reviews Farhan's reminder code, two people understand it. If Farhan is ill in launch week, the work does not stop.
- Keeping the code consistent. Reviews keep names, structure and error handling in the shared style, so the code base reads like the work of one careful team.
Review is not a replacement for tests, and it is not a gate where a senior person approves or rejects juniors. Juniors review seniors' code too; it is one of the fastest ways to learn a code base.
What a reviewer looks for
The formatter and linter from the previous page already handle layout, so human time goes to things tools cannot judge. A checklist keeps reviews consistent:
| Question | ClinicQueue example |
|---|---|
| Does it do what the issue and its acceptance criteria ask? | The issue says "retry a failed SMS once"; the code retries three times. |
| Is it correct at the edges? | What if the patient has no phone, or the appointment is cancelled between the first try and the retry? |
| Are there tests, and do they pass? | A test for "failed, then sent" and one for "failed twice". |
| Is it readable and in the team's style? | Clear names, no magic numbers (MAX_SMS_RETRIES = 1), small functions. |
| Does it fit the design? | Retry logic belongs in the reminder module, not in the screen code. |
| Is it safe? | No phone numbers or message text written to the log; no secret key in the code. |
| Is anything missing? | A database change for the new sent_status value; a line in the change log. |
Giving and receiving review comments
Reviews are conversations between colleagues about code, not judgements of people. The way a comment is written decides whether it helps.
Writing comments that help
- Talk about the code, not the person: "this function returns before saving" rather than "you forgot to save".
- Explain why, so the author learns the rule, not only the fix.
- Ask when you are not sure: maybe the author knows something you do not.
- Mark how important a comment is. Many teams prefix small, optional points with "nit:" (short for nit-pick) so that the author knows which comments must be fixed.
- Say what is good, too. A short "nice test for the cancelled case" tells the author what to keep doing.
Example:
Unhelpful: "This is wrong."
Unhelpful: "Why would you ever do it like this?"
Helpful: "If the appointment is cancelled after the first SMS fails, the retry still sends.
Could we check the status again before retrying? Patients may get a reminder
for a cancelled visit."
Helpful: "nit: `n` could be `retries_left`, easier to read. Not blocking."
Helpful: "Question: is one retry enough? The issue says once, so fine if that was agreed."Receiving comments
When Kwame comments on your change, he is helping the product, not attacking you. Thank people for finding problems; it is much better that a colleague finds them than a patient. If you disagree, explain your reason in the thread; if the discussion goes around twice without agreement, talk for five minutes instead of writing more. Answer every comment, either with a fix or with a reason, so the reviewer knows nothing was missed.
Small pull requests
A pull request (PR; some tools call it a merge request) is a request to merge the commits on your branch into the main branch, with a place for review comments. Small pull requests get much better reviews. A reviewer can hold a change of a hundred lines in their head and think about each one; faced with two thousand lines, most people skim and approve. Small PRs are also merged sooner, conflict less with others' work, and are easier to undo if something goes wrong.
How to keep them small: one issue per PR; separate refactoring from behaviour changes (exactly the habit from the previous page); and split a big feature into steps that are each safe to merge, for example "add the sent_status column" before "retry failed SMS". A good PR description saves the reviewer time:
Template:
Title: Retry a failed reminder SMS once (#57)
What: When the SMS provider reports a failure, the reminder is retried once after
10 minutes. Status goes pending -> failed -> sent, or stays failed.
Why: Issue #57: Rina sees patients who missed the reminder because of one failed send.
How to test:
1. Run the test suite (new tests: test_retry_once, test_no_retry_if_cancelled).
2. In the test environment, set the fake SMS provider to fail once and book a slot.
Not included:
Showing failed reminders on the front-desk screen (issue #58).Branches, pull requests and a releasable main
A branch is a separate line of commits, so you can work on a change without disturbing anyone else. ClinicQueue uses a simple, very common workflow, often called a feature-branch workflow:
- The main branch always holds code that works and could be released. Nobody commits to it directly.
- For each issue, the developer creates a short-lived feature branch from main, named after the issue.
- They commit small steps on the branch and push it to the shared repository.
- They open a pull request. Automated checks run (formatter, linter, tests), and at least one teammate reviews.
- When the checks pass and the review is approved, the branch is merged into main and deleted.
Example:
main o-----o----------------o-----------o------ always releasable
\ \ / /
57-sms-retry \ o----o-----o-' / PR #61, reviewed by Aiko
\ /
58-failed-list o-------o--------o---------' PR #62, reviewed by Kwame
o = a commit a line joining main = a reviewed pull request being mergedThe Git commands for this flow are few. They are shown here only as a reminder; their details belong to Git, APIs and Backend for AI: Beginner.
Example:
git switch main
git pull get the latest main
git switch -c 57-sms-retry new branch for issue 57
git add reminders.py test_reminders.py
git commit -m "Retry a failed reminder SMS once"
git push -u origin 57-sms-retry then open a pull request in the shared repositoryWhy "main stays releasable" matters
If main is always working, the team can release whenever Nadia needs a fix, a new developer can start from main and trust it, and when something breaks, the cause is in the latest merged pull request. The price is discipline: unfinished work stays on branches (or behind a switch that keeps it hidden), and a broken main is fixed before anything else.
How long should branches live?
Teams differ here. Some keep feature branches for a week or more and review each one carefully. Others merge very small changes into main several times a day, relying on pairing, fast reviews and strong automated tests. Long-lived branches drift away from main, and merging them becomes painful. For a beginner team like ClinicQueue's, a good default is a branch per issue, merged within a day or two.
Commits, done and issues
Commit messages
The commit history is the project's memory. Months later, a commit message is often the only place that says why a line changed. A useful message has a short summary line in the imperative ("Retry …", "Fix …", "Add …"), a blank line, and then, if needed, a body that explains why and refers to the issue. Many teams keep the summary line to roughly 50 characters; that is a common convention, not a rule built into Git.
Example:
Weak: "fix" "changes" "wip" "final version 2"
Better: Retry a failed reminder SMS once
The SMS provider sometimes rejects a message for a short time.
One retry after 10 minutes covers most of these cases without
sending duplicates. Cancelled appointments are not retried.
Refs #57
Conventional Commits style (optional):
feat(reminders): retry a failed SMS once
fix(queue): sort patients by time, not by text
refactor(queue): split print_day into small functionsThe last three lines use Conventional Commits, one popular convention, not a requirement; Releasing and Maintaining Software explains its format and how it links commit messages to version numbers.
A Definition of Done
"Done" means different things to different people: "I wrote the code", "it is merged", "it is in production". A Definition of Done is a short, shared checklist that every item must meet before anyone calls it done. In the 2020 Scrum Guide, the Definition of Done is the commitment for the Increment; teams that do not use Scrum benefit from one just as much. ClinicQueue's is the full version of the short Definition of Done on Agile, Scrum and Kanban:
Template:
Definition of Done (ClinicQueue)
[ ] Acceptance criteria of the issue are met and checked by someone other than the author
[ ] Automated tests written for the new behaviour; all tests pass
[ ] Formatter and linter pass
[ ] Pull request reviewed and approved by at least one teammate
[ ] Merged into main; main still passes all checks
[ ] Deployed to the test server and checked there
[ ] Screens work on a small phone
[ ] User-facing change noted in the change log; README updated if setup changed
[ ] No personal data (phone numbers, names) in logs or test dataThe list is short on purpose. A list of thirty items is not followed; a list of nine, checked every time, is. The team reviews it in a retrospective when they notice a recurring problem.
Issue tracking
An issue tracker holds every piece of work as an issue (also called a ticket): a user story, a bug or a task, each with a number, a description, acceptance criteria, an owner and a status. Its value comes from linking things: the issue number appears in the branch name (57-sms-retry), the commit message (Refs #57) and the pull request, so anyone can go from a line of code back to the reason for it, and from a requirement forward to the code. That is the traceability idea from the requirements chapter, kept up to date with almost no extra work. The tracker's board is the same kind of board you saw on Agile, Scrum and Kanban.
Pair programming
In pair programming, two developers work on the same change at one computer (or one shared screen). One, often called the driver, types; the other, the navigator, reviews each line as it is written, thinks ahead and spots problems; they swap roles often. The review happens continuously, so many teams accept a paired change with a lighter separate review. Pairing costs two people's time for one task, so it pays off most for difficult or risky code (the booking rules that prevent double booking), for teaching a newcomer the code base, and for tricky bugs. For routine changes, working alone plus a normal review is usually enough. Pairing is tiring; short sessions with breaks work better than whole days.
Where this shows up at work
- In most software companies no code reaches main without a pull request and at least one approval; your first weeks in a job will include many reviews.
- Open-source projects work the same way: outsiders propose changes as pull requests and maintainers review them, so a respectful, clear PR is how you get your contribution accepted.
- Freelancers working alone still use branches and write PR descriptions; they review their own change the next morning, and the client can see a clear history.
- Release managers rely on a releasable main and clear commit messages to decide what goes into the next version.
Common mistakes
- Huge pull requests. A two-thousand-line PR gets a quick "looks good" and hides bugs. Fix: one issue per PR, refactoring separate, big features split into safe steps.
- Review as a power game. Harsh or personal comments make people hide work and avoid asking. Fix: comment on code, explain why, mark optional points, and say what is good.
- Committing directly to main. Unreviewed code and half-finished features land in the releasable branch. Fix: protect main in the repository settings so changes arrive only through reviewed pull requests.
- Long-lived branches. A branch kept for three weeks drifts away from main and its merge breaks things. Fix: small issues, merge within a day or two, pull from main often.
- "Done" without a definition. Items are called done while tests are missing. Fix: a short Definition of Done that the whole team checks every time.
Try it yourself
- Easy: Rewrite these review comments so that they are respectful and useful: (a) "This is a mess." (b) "Wrong, use a constant." (c) "Did you even test this?"
- Medium: Aiko has a branch with 1,800 changed lines: the new failed-reminders list on the front-desk screen, a rename of every variable in the queue module, a new database column, and a fix for a sorting bug she found on the way. Propose how to split it into pull requests, in which order they should be merged, and write a commit summary line for each.
- Hard: Nadia reports that last week a patient got a reminder for a cancelled appointment. Using the workflow on this page, describe the path from report to release: the issue, the branch, the commits, the pull request (with a short description), the review checklist points that matter most here, and the Definition of Done items that must be checked before you tell Nadia it is fixed.
Answers
- Model answers: (a) "This function finds, formats and prints in one place, which makes it hard to follow. Could we split it into smaller functions, like we did for
print_day?" (b) "The 15 here is the slot length; could it useMINUTES_PER_PATIENTso it changes in one place?" (c) "What happens when the phone number is empty? I could not find a test for that case; could you add one?" A good answer names the specific problem, explains why it matters, suggests a direction or asks a real question, and does not judge the person. - One reasonable split: PR 1 "refactor(queue): rename variables in the queue module" (no behaviour change, easy to review quickly); PR 2 "fix(queue): sort patients by time, not by text" (a small behaviour change with a test, useful on its own and releasable at once); PR 3 "feat(reminders): add a column for failed reminders" (the database change); PR 4 "feat(queue): show failed reminders on the front-desk screen" (depends on PR 3). Order: the rename first so later PRs build on clean code, or the bug fix first if it is urgent for the clinic; PR 3 must come before PR 4. A good answer separates the refactoring from the behaviour changes, keeps the bug fix on its own, puts the database change before the screen that uses it, and gives each PR one clear purpose. Plain summary lines without the Conventional Commits prefix are also fine.
- Model answer: Kwame opens bug issue #64 "Reminder sent for cancelled appointment" with steps to reproduce, expected and actual result. Farhan updates main and creates branch
64-no-reminder-after-cancel. He first writes a test that books, cancels and runs the reminder job, and sees it fail; then fixes the reminder job to check the status just before sending. Commits: "Add test: no reminder for a cancelled appointment" and "Check appointment status before sending a reminder (Refs #64)". The PR description says what changed, why (#64), how to test, and what is not included. Review points that matter most: correctness at the edges (cancelled after the reminder was planned; cancelled and rebooked; retry after cancel), tests for those cases, and no patient data in logs. Definition of Done: acceptance criterion checked by someone other than Farhan (Kwame), all tests and checks pass, reviewed and merged, main still passes all checks, deployed to the test server and checked there, change log line "Fixed: reminders were sent for cancelled appointments". Only then is the fix released and Nadia told, with the release date. A good answer has a test that fails before the fix, links everything to the issue number, and does not call it done at "code written".
Summary
- Code review finds defects early, spreads knowledge and keeps the code consistent; a checklist focuses it on correctness, tests, readability, design, safety and missing pieces.
- Good review comments are about the code, explain why, mark what is optional, and say what is good; authors answer every comment.
- Small pull requests with clear descriptions get real reviews; keep refactoring separate from behaviour changes.
- In a feature-branch workflow every change goes from a short-lived branch through a reviewed pull request into a main branch that stays releasable.
- Clear commit messages, a short Definition of Done and an issue tracker link each change to its reason; pair programming is continuous review, best for hard or risky work.
Next: Software Quality, Testing and QA: how to decide what to test, design test cases for ClinicQueue, and report bugs so they get fixed.

