How to Take Notes During Code Review

What Code Review Teaches That No Other Source Can

Code review is one of the most intensive learning experiences in software engineering. In a single review, an engineer encounters: specific decisions made by the author and the reasoning behind them; implicit assumptions about the codebase's conventions and constraints; architectural trade-offs made visible in the concrete implementation; potential failure modes and edge cases identified by other reviewers; and the gap between what the author intended and what a fresh reader understood.

This is a significant amount of knowledge — specific, contextualized, directly relevant to the codebase the reviewer works in. It's also almost entirely ephemeral: it exists in the review thread, the reviewer reads it, and it's gone from active memory within days.

Most engineers don't take notes during code review because the code review feels like a task (respond to this PR, leave comments, approve or request changes) rather than a learning event. The task lens is not wrong — code review is a task — but the combination of task + learning produces more value than either alone.

The engineers who grow fastest in a codebase are often the ones who treat code review as a source of knowledge about the codebase's conventions, architectural decisions, and failure modes — not just as a queue to clear.

---

What to Note (and What Not To)

Not every observation in a code review is worth capturing. The target is knowledge that will be useful in the future — either for writing code, for future reviews, or for understanding the system.

Worth noting:

Patterns you didn't know the codebase used: "The team uses the Result type pattern for all database operations — success or failure, never exception. I didn't know we were this consistent about it. Note: follow this pattern in all new service layer code."

Anti-patterns explicitly called out by reviewers: "Reviewer noted that direct database queries in controllers violate the repo layer pattern; everything should go through the repository interface. This is the first time I've seen this called out explicitly — is it a hard convention?"

Architectural decisions surfaced during review: "Senior engineer's comment explained why the payment service uses optimistic locking instead of pessimistic: the update frequency is low enough that conflicts are rare, so we optimize for the common case. This is documented nowhere else."

Your own review observations you want to apply next time: "I left a comment about the missing error handling on the external service call; the author explained they're relying on the circuit breaker middleware. I need to understand how that middleware works before I leave similar comments."

Patterns that could be abstracted: "Third time I've seen this date range validation code in slightly different forms. This should probably be a utility function. Note this as a potential small refactor item."

Not worth noting:

• Code changes that are entirely obvious and unsurprising
• Review comments that were resolved by a trivial fix with no learning
• Naming debates without an architecture or convention implication
• Changes that are specific to the business logic of one feature and unlikely to recur

---

The Note Format

Code review notes are a personal reference, not a formal document. The format that works:

Date and PR: When the note was taken and which PR it came from. Useful for context when the note is read months later.

The pattern or observation: What you learned. Written as if explaining it to yourself six months from now: specific, with the key detail, not "something about locking" but "optimistic locking in the payment service: used because conflict rate is < 0.1%; circuit breaker middleware handles cascading failure."

Whether it's confirmed or tentative: Is this an established team convention, or was it a single reviewer's preference? "Confirmed: senior engineer stated this is a hard convention" vs. "Tentative: one reviewer mentioned this; needs verification."

Action item (if any): Is there anything to do as a result of this observation? A refactor to propose, a convention to ask about, documentation to add, a pattern to start applying?

CODE REVIEW NOTE

Date: 2026-10-18
PR: #847 — Payments service batch processing refactor

OBSERVATION:
Database transactions are always started in the service layer, never in 
controllers or repositories. The pattern:
  - Controller calls service method
  - Service method starts transaction, calls repository methods, commits/rolls back
  - Repositories never start transactions

CONFIRMATION: "Please don't start transactions in the repository — all 
transaction management is in the service layer. This gives us a single 
place to manage transaction scope." — @senior-eng PR comment

STATUS: Confirmed hard convention

ACTION: Check my recent PRs for any repository-level transactions; 
fix if found. Apply consistently to new service methods.

---

When to Take Notes

The optimal time to note a code review observation is during the review — when the context is fully loaded and the observation is fresh. The practical constraint is that stopping to write a formatted note interrupts the review.

The two-step approach: During the review, leave a rough scratch note (a short phrase or bullet, not a formatted entry). After the review is complete, spend 5-10 minutes turning the scratch notes into formatted reference entries.

Scratch notes during review: "optimistic locking - why?", "Result type - all DB ops?", "no transactions in repo layer"

Formatted entries after review: complete notes in the format above.

The scratch notes ensure the observations are captured when fresh; the formatting session makes them useful for later retrieval.

---

The Review Observation as Team Knowledge

Individual code review observations that have team-wide implications belong in the team knowledge base, not just in personal notes.

The escalation trigger: If a review reveals a convention that isn't documented anywhere, and you're confident it's intentional (confirmed by a senior engineer's comment), add it to the team knowledge base. "Transactions are started in the service layer only" is a convention that affects every engineer on the team; it belongs in the team's coding conventions document.

This is the "answer once, write it down" principle applied to code review: when a review surfaces an implicit convention, making it explicit prevents the same conversation from being repeated in future reviews.

The PR comment → KB entry pipeline: Substantive PR comments that explain a convention, a rationale, or a pattern are candidates for KB entries. Not every comment — only the ones that answer a question that other engineers are likely to ask.

---

Building a Code Review Pattern Library

Over time, code review notes accumulate into a personal pattern library: a searchable record of coding conventions, architectural patterns, and anti-patterns encountered in this codebase.

The pattern library is most useful for:

Before reviewing: Search for "payments service" or "transactions" to recall relevant conventions before starting a review. This makes the review more accurate — you're less likely to flag something as wrong that is actually the established convention, and more likely to flag genuine violations.

Before writing new code: "We're adding a new endpoint to the user service — let me check my review notes for user service patterns." Reviewing your own notes before writing code reduces the number of patterns you need to ask about in your own PR.

For raising conventions explicitly: "I've now seen this pattern called out in four reviews but I don't see it in our conventions document. Should we add it?" The accumulated evidence across multiple reviews makes the case for formalization.

As a junior engineer's accelerant: A junior engineer who takes code review notes systematically builds a codebase understanding that accelerates dramatically relative to one who treats each review as an isolated task. The pattern library becomes the accumulated context that senior engineers have built over years.

---

Tools

Code review notes don't require special tooling. Any system that is searchable, tag-filterable, and accessible during code review sessions works. Options:

A markdown file or folder in your personal wiki (Obsidian, Notion): Organized by service/system. Each entry is a dated note with the pattern, status, and action item. Full-text searchable. The recommended approach for most engineers.

A GitHub Gist or repository note: If your code reviews happen in GitHub, a parallel GitHub note in a private Gist or repository has the advantage of being in the same tool. Less organized than a dedicated wiki but low friction.

An Anki or flashcard deck for conventions: For engineering conventions you want to internalize deeply (not just reference), converting them to flashcards produces retention. "When do we start transactions?" → "In the service layer, always. Never in controllers or repositories." This is a complement to the reference notes, not a replacement.

---

Worked Example: A Junior Engineer's Code Review Log

Setup: Mia is a junior engineer three months into her first engineering job. She has written approximately 15 PRs and reviewed approximately 30. She's noticed that the same conventions come up repeatedly in reviews of her PRs, but she keeps having to ask about them.

What she does:

She creates a "Code Review Notes" section in her personal Notion wiki. After each review (her own or someone else's), she spends 5-10 minutes adding entries for anything she learned.

After one month: 22 entries covering error handling conventions, testing standards, service layer patterns, and several codebase-specific architectural decisions.

What changes: She starts checking her notes before writing PRs. In the next month, her PRs receive 40% fewer "convention" comments than in the prior month — not because the conventions changed, but because she's now writing code that already follows them. Her review cycle time drops.

She identifies three conventions that aren't in the team documentation and mentions them in a 1:1 with her tech lead. Two are added to the team wiki. One was a single reviewer's preference, not a convention.

---

Key Takeaways

1. Code review is a learning event, not just a task: the patterns, conventions, and architectural decisions surfaced in reviews represent some of the most contextualized, practical knowledge available about a codebase — capturing it rather than letting it fade is a compounding advantage.
2. Take scratch notes during review, format them after: stopping to write formatted notes during a review interrupts the review; rough notes during + 5-10 minutes formatting after is faster overall and produces better notes.
3. Mark observations as confirmed vs. tentative: a single reviewer's preference is not a team convention; a senior engineer's explicit statement about a pattern is; knowing which is which prevents incorrect generalization.
4. Observations with team-wide implications belong in the team knowledge base: when a review surfaces an implicit convention, adding it to the KB makes it explicit and prevents the same conversation from recurring in future reviews.
5. Searching review notes before writing code and before reviewing reduces cycle time: code that already follows conventions needs fewer convention comments; a reviewer who knows the relevant conventions leaves more accurate feedback.

---

Conclusion

Taking notes during code review converts the learning embedded in review threads — patterns, conventions, architectural decisions, anti-patterns — from ephemeral observations into a searchable, reusable personal reference. The practice is low-overhead (10-15 minutes per review) and compounding: each month of note-taking produces a more complete picture of the codebase's conventions and a reviewer who asks better questions, writes code that requires fewer revision cycles, and contributes to the team's shared knowledge. The engineer who treats code review as a learning event, not just a queue to clear, is the one whose code review outcomes improve fastest.

See also: Best Web Clipper Extensions.