Essential Code Review Principles Every Engineer Should Master

Overview

The author, a backend engineer at Tencent, expands on a previous piece about the value of code review and shares a systematic collection of architectural principles, engineer habits, and typical anti‑patterns to guide teams toward higher code quality and smoother collaboration.

Well‑Known Architecture Principles

Details Are Architecture

Design and architecture are inseparable; low‑level implementation details belong in the architecture documentation just as high‑level concepts do.

Bind Code and Documentation (Self‑Explaining Principle)

Write documentation that lives next to the code—use godoc‑style comments, keep explanations close to the implementation, and supplement with concise README files when needed.

ETC Value (Easy‑to‑Change)

ETC is a guiding value, not a strict rule, helping you decide between alternatives and supporting agile, rapidly changing projects.

DRY (Don’t Repeat Yourself)

DRY is the most critical coding principle; avoid duplication at all costs.

Orthogonality (Avoid Global Variables)

Strive for high cohesion and low coupling; replace global state with interfaces, dependency injection, or message‑based communication.

Reversibility Principle

Design decisions should be reversible; avoid hard‑coded assumptions about data types, storage, or system limits.

Dependency Inversion Principle (DIP)

package dip

type Botton interface {
    TurnOn()
    TurnOff()
}

type UI struct {
    botton Botton
}

func NewUI(b Botton) *UI { return &UI{botton: b} }

func (u *UI) Poll() {
    u.botton.TurnOn()
    u.botton.TurnOff()
    u.botton.TurnOn()
}

package javaimpl

type Lamp struct {}

func NewLamp() *Lamp { return &Lamp{} }

func (l *Lamp) TurnOn() { fmt.Println("turn on java lamp") }
func (l *Lamp) TurnOff() { fmt.Println("turn off java lamp") }

package main

import (
    "javaimpl"
    "pythonimpl"
    "dip"
)

func runPoll(b dip.Botton) {
    ui := NewUI(b)
    ui.Poll()
}

func main() {
    runPoll(pythonimpl.NewLamp())
    runPoll(javaimpl.NewLamp())
}

DIP decouples high‑level modules from low‑level implementations, enabling flexible composition.

Pure Text Documentation

Prefer human‑readable plain text for design specifications unless a specialized format is truly required.

Design by Contract (DBC)

Use explicit contracts (e.g., gRPC + swagger) to define and verify component interfaces; TDD can help enforce these contracts.

Fail Fast (Early Crash)

Allow programs to fail early with clear error propagation; use error wrapping in Go 1.13+ instead of pervasive panics.

Decouple Code for Easy Change

Eliminate strange cross‑package dependencies.

Avoid modifications that ripple through unrelated modules.

Reduce fear of change among developers.

Command‑Only, No Queries

Write functions that issue commands without querying unnecessary state, keeping them simple and easy to modify.

Avoid Method Chaining

Pass only the minimal data a function needs; avoid long call chains that increase coupling.

Inheritance Tax (Prefer Composition)

Inheritance creates hidden coupling across class hierarchies; favor composition and interfaces to keep code adaptable.

Other Principles

Unix Philosophy basics (modularity, clarity, composition, separation, simplicity, thriftiness, transparency, robustness, representation, common sense, silence, remediation, economy, generation, optimization, diversity, extensibility).

SOLID principles (SRP, OCP, LSP, ISP, DIP).

Engineer’s Self‑Improvement

Paranoia : Be obsessive about code details to maintain quality in chaotic environments.

Control Entropy : Treat software entropy like physical entropy; refactor before it becomes unmanageable.

Design for Testability : Write code with testing in mind; consider testability during implementation.

Testing Practices : Adopt early, frequent, automated testing; treat tests as first‑class artifacts.

Unified Terminology : Use consistent domain language to avoid miscommunication.

Don’t Program to Requirements : Focus on business models rather than fleeting UI or requirement details.

Pursue Code Beauty : Treat code as an art form—clean, readable, and aesthetically pleasing.

Common Cases That Don’t Rise to Principles

Leave obscure logic without clear comments.

Insert TODOs without action plans.

Discard useful error information.

Write slow automated tests.

Ignore entropy‑related problems and delay fixes.

Over‑document or hard‑code IPs and other mutable values.

Use numbered lists (1,2,3,4) where descriptive naming is clearer.

Rely on init functions without necessity.

Ignore shadow writes and other subtle bugs.

Outlook

The author hopes the collection of principles, habits, and examples helps teams cultivate strong code‑review cultures, improve software quality, and foster continuous learning. Embracing these ideas should lead to better collaboration, lower technical debt, and more resilient systems.