Code Review Etiquette

Code reviews are presented as a normal part of software work, especially in teams, and the article argues that agreed-upon etiquette matters because critiques can feel personal. It says good reviews help catch mistakes, improve readability, support learning, and keep code changes small and clear.

The article warns that sloppy or harsh feedback can damage trust, reduce productivity, and lower code quality over time. It recommends removing personal references, keeping passionate conversations quiet, reviewing the code rather than the author, staying context-specific, and remembering that old judgments about technologies can change.

Reading notes

#

• Code reviews are a shared process for discussing code in tools like GitHub, in pair programming, or through other review platforms.
• Regular reviews help teams stay aligned, catch small errors, and help newer developers learn the codebase.
• Smaller code changes are easier to review and can make reviews more frequent and manageable.
• Reviewers can teach and mentor, while junior reviewers can improve readability by asking questions.
• Solo developers can still seek outside feedback through meetups, GitHub, Slack, Reddit, or Twitter.
• Harsh or careless reviews can trigger defensiveness and hurt feelings.
• A review should explain why something is wrong, where it went wrong, and how to avoid repeating the mistake.
• Using personal references such as “you” or “we” can make comments feel more personal; removing them makes the feedback clearer.
• Critical feedback works better when the person receiving it is engaged and when the tone stays calm.
• Comments should focus on the code in front of the reviewer, not on unrelated lessons or broad judgments.
• Broader discussions are better handled outside the review itself.
• Historical context matters because technologies and assumptions can change over time.
• The article lists Alexjs, Grammarly, Write Good, and Awesome Writing Tools as resources for improving writing and review tone.
• The author says the article is based on mistakes they have made and is meant to help others discuss code more openly.