Why Code Review Matters: Principles for Writing Better Backend Code

Preface

As a member of the company’s Golang code‑review committee, I have examined many code reviews and noticed that many engineers need to improve both their review skills and their ability to write good code. I share my ideas and thoughts here.

Why Technical Staff, Including Leaders, Should Do Code Review

"Talk is cheap, show me the code." Knowing a design principle is easy; applying it is hard. Many people only claim to understand a concept without actually practicing it, leading to a false sense of security.

Code is where design ideas become reality. During review, developers can discuss concrete implementations, learn from each other, and converge on the best practices for the team. Even leaders who don’t write code can still provide valuable feedback on practices.

Why Reviewers Should Think About and Summarize Best Practices

An architect masters many design principles, applies them across languages and toolchains, and controls the maintainability of large codebases.

Tricks and clever techniques

Domain foundations (e.g., John Carmack’s graphics breakthroughs)

Theoretical research (e.g., Li Kaifu’s early speech recognition)

Product success stories

Best practices that anyone can adopt

Improving best‑practice methodology is the path from ordinary engineer to architect.

Root Causes of Bad Code

Duplicated Code

// BatchGetQQTinyWithAdmin gets QQ tinyID, needs admin tiny and login state
func BatchGetQQTinyWithAdmin(ctx context.Context, adminUin uint64, friendUin []uint64) (adminTiny uint64, sig []byte, frdTiny map[uint64]uint64, err error) {
    var friendAccountList []*basedef.AccountInfo
    for _, v := range friendUin {
        friendAccountList = append(friendAccountList, &basedef.AccountInfo{AccountType: proto.String(def.StrQQU), Userid: proto.String(fmt.Sprint(v))})
    }
    // build request body ...
}

When the initial protocol is poorly designed, each new consumer rewrites similar logic, leading to duplicated fragments that become hard to maintain.

Early Decisions Lose Effectiveness

// Update performs incremental updates
func (s *FilePrivilegeStore) Update(key def.PrivilegeKey, clear, isMerge bool, subtract []*access.AccessInfo, increment []*access.AccessInfo, policy *uint32, adv *access.AdvPolicy, shareKey string, importQQGroupID uint64) error {
    info, err := s.Get(key)
    if err != nil { return err }
    // ... complex logic ...
    return nil
}

As more logic is added, the function grows beyond 80 lines, mixing top‑level flow with deep details, making it hard to follow and increasing the risk of bugs.

Premature Optimization

Often discussed, but omitted here for brevity.

Lack of Rigor in Reasonableness

Statements like "both ways are ok, pick any" hinder quality.

Over‑use of Object‑Oriented Encapsulation

template<class _PKG_TYPE>
class CSuperAction : public CSuperActionBase {
public:
    typedef _PKG_TYPE pkg_type;
    typedef CSuperAction<pkg_type> this_type;
    ...
};

Deep inheritance trees make it difficult for junior engineers to understand and modify code safely.

No Design at All

Starting a project without any design leads to massive, monolithic files that are impossible to maintain.

Metaphysical Thinking Required

Engineers must move from merely following instructions to building a mental model that connects technical details with system requirements.

Model Design

Designing without reading the OAuth2.0 RFC leads to reinventing a broken solution.

UNIX Design Philosophy

"Those who don’t understand Unix will inevitably reinvent a broken Unix." – Henry Spencer, 1987.

Keep It Simple Stupid (KISS)

True simplicity requires deep understanding of the problem, not just superficial brevity.

Composition Principle

Prefer composition over inheritance to keep modules interchangeable and reduce cognitive load.

Frugality Principle

Write the smallest program that works; avoid unnecessary bloat.

Transparency Principle

Code should be visible and understandable so reviewers can quickly grasp behavior.

Common‑Sense Interface Principle

Design APIs that are intuitive; avoid overly clever naming that increases learning cost.

Silence Principle

Only log when necessary and include enough context to be useful.

Remedy Principle

When an exception occurs, surface it immediately with sufficient diagnostic information.

Concrete Practices for Golang

Enforce 100% code‑format compliance.

Never let a file exceed 800 lines; split when it does.

Functions should stay under 80 lines; refactor otherwise.

Limit nesting depth to four levels; use early returns.

if !needContinue {
    doA()
    return
}

doB()
return

Early returns decouple logic branches.

Organize code hierarchically: package → directory → file → struct → function.

Use multi‑level directories even if some contain a single sub‑directory.

Continuously refactor old code that violates principles.

Encourage asking questions during review to accelerate growth.

Log sparingly but include key identifiers.

Adopt trpc and align with leadership on code‑quality goals.

Eliminate duplication relentlessly.

Trunk‑Based Development

Keep review size under 500 lines to ensure thorough inspection and easier adjustments.

Recommended Reading

Read "The Art of Unix Programming" for timeless engineering wisdom, and "Software Engineering at Google" for modern practices.

Author: cheaterlin, Tencent PCG backend engineer