Writing on software, systems, and hard-won lessons.
Writing on developer experience, systems thinking, and the mistakes behind both - covering AI workflows, continuous improvement, and the mental models that drive better decisions.
Writing on developer experience, systems thinking, and the mistakes behind both - covering AI workflows, continuous improvement, and the mental models that drive better decisions.
When the reviewer isn't spending cognitive load on things the author or CI should have caught, they can go deeper on the things that need human judgment.
It's hard to get the right balance between the extremes of spending too much time going line by line vs giving it a quick skim and seeing if CI tests pass. Code review should be a collaboration. The question I'm trying to answer here is "how can we make it easier for each other".
Small Pull Requests. PR size depends on complexity, but chunking projects into 2-5 hour tasks is practical. Split larger projects into stacked PRs and use feature flags (eg. if internal testers) to merge and deploy stable work in progress safely.
Big Pull Requests. Sometimes large pull requests are unavoidable. When this happens, try to point out any areas that require extra attention or if there's any files that can be skimmed.
Self-review. Ensure the CI tests have passed. Get copilot to review and add PR Summary. Then read through the changes yourself as if you were reviewing for someone else. You catch things others will miss, and a fresh-eyes reviewer will catch things you miss.
Explain the unexpected. Add a comment for exceptions to the rule, so the reviewer doesn't have to ask.
Push back when needed. Remember the author has a bigger picture view of the entire change and the discussions had along the way. The reviewer might make a suggestion that is logical in isolation, but there might be a good reason why it's not worth the effort.
Follow up. Occasionally everyone will miss a notification or review request. It doesn't mean they are avoiding it. Be proactive and follow-up the next morning, say something like "Hey, just wanted to check if you had a chance to look at my PR?"
The three pillars of our code guidelines:
Distributed rigour: Don't go hunting edge case functional bugs (still flag obvious ones). No verifying requirements (trust the author and tester). Style and formatting should be covered by linters.
Look for red flags. Fetching all rows then filtering in code instead of letting the query do it? Logging something that could be PHI? Is access control covered on both frontend and backend, or just one?
While scanning for trouble. Reading is 80%, writing is 20% of our job. So I focus on maintainability. Could I explain how this works and why, to another developer?
Give useful feedback: Be specific and explain why it matters. Tag severity especially if a single suggestion may take more than 5 mins to address: [Important], [Nice to have], [FYI for next time]
When to discuss. If there's 20+ comments, or major time consuming changes, consider discussing with the person. There might be a good reason, like it's just a prototype or perhaps they are new to the project and not aware of the conventions.
Note: For teams that don't have testers or QA Team or do have junior developers. Then extra effort will be required to check correctness. That means the distributed rigour becomes less distributed.
Balance. We don't want slow delivery or frustrated devs. And bugs in production or mounting technical debt is not ideal to say the least. The code review process should evolve with the project and team, trying to strike a balance.
Automation. PR checks with linting, CI tests, security scans, AI code review tools with project specific instructions are great.
Try to make the right way the easy way. If the same feedback appears repeatedly, that's time to review the system and discuss with the team. Try simplifying the process where possible, perhaps there's a nice to have that's not worth the effort?
Pull request templates. Create templates so it's easier for the author to follow the process.
| Do | Don't |
|---|---|
| Approve when it's better, even if not perfect | Hold PRs hostage for polish |
| Focus on "can I understand and maintain this?" | Re-verify every requirement |
| Flag obvious bugs you notice | Trace through all logic paths |
| Explain the why behind feedback | Just say "this is wrong" |
| Talk if there's too much to write | Leave 30 comments |
| Respond within a day | Let PRs sit for a week |