Why Code Review Matters: Principles for Writing Better Backend Code

Introduction

As a member of the company’s Golang code‑review committee, the author reflects on the gap between knowing good design principles and actually applying them in code, emphasizing that code review is the bridge that turns theory into practice.

Why Technical Staff and Leaders Must Do Code Review

Code is the concrete manifestation of design ideas; reviewing it forces concrete communication, surface‑level discussions, and mutual learning. Even leaders who do not write code should provide concrete improvement suggestions when reviewing.

Common Pitfalls in Code Quality

Duplicate code : Re‑implementing similar request‑building logic across services leads to maintenance nightmares and hard‑to‑track bugs.

Early decisions become obsolete : Initial implementations may be clean, but later extensions can bloat functions and break logical layering.

Poor optimization timing : Over‑optimizing before a problem is proven adds unnecessary complexity.

Lack of rigor : Accepting any design without strict scrutiny creates a false sense of security.

Over‑use of inheritance : Deep inheritance trees make it hard for newcomers to understand and modify code; composition is preferred.

Design Philosophies and Principles

The author lists several engineering principles, each illustrated with short anecdotes or code snippets.

Keep It Simple Stupid (KISS)

Simplicity requires deep understanding of the problem domain; a well‑designed OAuth2 flow exemplifies a simple yet complete solution.

Composition Over Inheritance

Using composition (e.g., assembling a http.Request from independent parts) reduces coupling and eases future changes compared with deep class hierarchies.

Frugality Principle

Write the smallest code that works; deleting unnecessary lines often yields more satisfaction than adding new ones.

Transparency Principle

Code should be easy to read and reason about; clear naming, limited nesting depth, and early returns improve mental models.

Logging Discipline

Log only essential information; excessive logging obscures real issues.

Error‑Handling Principle

When an exception occurs, abort quickly and provide rich diagnostic data; distinguish between program errors and logical errors.

Concrete Practices for Go Projects

Enforce 100% code‑format compliance.

Keep files under 800 lines and functions under 80 lines.

Limit nesting depth to four levels; use early returns to reduce nesting.

Organize code hierarchically: package → directory → file → struct → function, avoiding redundancy.

Prefer a single repository for most code; extract truly generic libraries into separate repos for safe refactoring.

During review, focus on core struct definitions, interfaces, and model boundaries; treat other code as implementation details.

// Example of duplicated request building (simplified)
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))})
    }
    req := &cmd0xb91.ReqBody{Appid: proto.Uint32(model.DocAppID), CheckMethod: proto.String(CheckQQ), AdminAccount: &basedef.AccountInfo{AccountType: proto.String(def.StrQQU), Userid: proto.String(fmt.Sprint(adminUin))}, FriendAccountList: friendAccountList}
    // ... send request ...
}

// Early‑return style to reduce nesting
if !needContinue {
    doA()
    return
}
// continue with main logic
doB()
return

Mainline Development

Keeping review size under 500 lines dramatically improves reviewer effectiveness and reduces the risk of missed defects. Smaller, incremental changes are easier to integrate and test.

Recommended Reading

The author suggests reading The Art of Unix Programming and Google’s Software Engineering at Google to deepen understanding of timeless engineering principles.