🔍 Code Review Language

Code reviews are a primary written communication channel in software teams. Comments that are too blunt ("this is wrong") damage team relationships, while overly vague comments ("maybe change this?") waste time. Non-native speakers often unintentionally sound harsh or unclear. Mastering code review language — from requesting changes to approving with feedback — is essential for effective collaboration.

Code review comment types: Nit (minor style suggestion — not blocking), Request changes (blocking — must fix before merge), Question (asking for clarification), Suggestion (non-blocking alternative approach), Praise (acknowledge good work), Blocking concern (security, correctness, performance issue requiring discussion). Using the right type sets clear expectations.

Constructive feedback patterns: focus on the code, not the person ("this function..." not "you wrote..."), ask questions instead of making demands ("what do you think about...?" vs "change this"), explain the why ("extracting this would make it easier to test because..."), use "nit:" for minor suggestions, and balance criticism with acknowledgement of what works well.

LGTM stands for "Looks Good To Me" — the standard code review approval phrase. Use "LGTM" for full approval, "LGTM with minor nits" when you approve but have small optional suggestions, "LGTM pending [X]" when you'll approve after a specific change, "LGTM!" for enthusiastic approval of excellent work. It originated in open-source GitHub culture and is now universal.

Nits (from "nitpicking") are minor, non-blocking comments about style, naming, or formatting preferences that don't affect correctness: "Nit: variable name could be more descriptive", "Nit: missing full stop in comment", "Nit: could use Array.from() here for clarity". Prefix with "Nit:" to signal it's optional. Don't block PRs on nits unless the codebase has strict style enforcement.

Tiered feedback approach: use "blocking" for correctness, security, or architectural issues, "should fix" for clear improvements that aren't critical, "consider" for alternative approaches, "nit" for style, "optional" for nice-to-haves. Always explain WHY a change is needed — "this could cause a race condition under load because..." is far more useful than just "this is wrong".

Positive review phrases: "Nice use of early return to reduce nesting", "This is a clean abstraction", "Good catch on the edge case", "The test coverage here is thorough", "Elegant solution to a tricky problem", "I like how this separates concerns clearly". Positive feedback motivates developers and reinforces good patterns — don't only comment on problems.

Responding to feedback: acknowledge specific comments ("Good point — fixed"), explain your reasoning if you disagree ("I kept it this way because X — happy to discuss"), ask for clarification on vague comments ("could you help me understand what you mean by X?"), and use "Done" or "Fixed in [commit]" once resolved. Avoid being defensive — treat reviews as collaborative improvement.

Bike-shedding in code reviews means spending excessive time on trivial issues (variable naming, formatting) while ignoring important ones (architecture, security). Reviewers should prioritise: (1) Correctness and security; (2) Performance and scalability; (3) Maintainability; (4) Style and naming. Automated linters handle most style issues — don't waste review time on things a tool can check.

Good PR descriptions include: the problem being solved, the approach taken, how to test the changes, screenshots for UI work, and links to related issues or documentation. A clear description reduces reviewer cognitive load and speeds up review. Think of it as a cover letter for your code — context helps reviewers focus on what matters most.