Principles and Practices for Effective Code Review and Software Design

Preface

As a member of the Golang sub‑committee of the company’s code committee, I have reviewed many pieces of code and observed that many engineers need to improve both their code review skills and their ability to write high‑quality code. This article shares my ideas and thinking.

Why Technical Staff and Leaders Must Do Code Review

Talking is cheap; showing code is hard. Understanding design concepts is easy, but applying them in practice is difficult. Code is the concrete manifestation of design ideas, and reviewing code enables concrete communication, learning, and the adoption of the team’s best practices.

Why Engineers Should Summarise Best Practices During Review

An architect masters many design principles, applies them across languages and toolchains, and can manage large codebases with high maintainability, testability, and operational quality.

Root Causes of Bad Code

Duplicate Code

When protocols are poorly designed, each developer may implement similar request‑building logic independently, leading to duplicated fragments that are hard to refactor and prone to bugs.

// BatchGetQQTinyWithAdmin ... (original Go function omitted for brevity)

Repeated implementations make future changes painful because every copy must be updated.

Early Decisions Lose Effectiveness

Initially correct code can become problematic as new logic is added, increasing function length and breaking logical cohesion.

// Update ... (original Go function omitted for brevity)

Long functions force reviewers to jump between high‑level flow and detailed branches, reducing comprehension.

Poor Optimization

Over‑optimizing early is a well‑known trap and is not discussed further.

Lack of Rigor

Statements like “both ways are OK, pick any” indicate a lack of strictness in code quality.

// Get ... (original Go function omitted for brevity)

Choosing the right locking pattern (e.g., using defer) improves readability and safety.

Excessive Object‑Oriented Design

Heavy inheritance hierarchies increase cognitive load; composition is often a better alternative.

template
class CSuperAction : public CSuperActionBase { ... }

Complex inheritance makes it hard for newcomers to understand and modify code safely.

No Design

Writing code without a clear model leads to massive, unmaintainable files and functions.

Metaphysical Thinking

Beyond technical details, engineers should develop a higher‑level engineering mindset that connects concrete code to system requirements, forming principles that guide future work.

Model Design

Good model design anticipates future product changes, avoiding costly migrations and enabling scalable architecture.

UNIX Design Philosophy

Quotes and principles from classic works emphasize the importance of simplicity, composability, transparency, and minimalism in software engineering.

Keep It Simple Stupid (KISS)

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

Composition Principle

Prefer composition over inheritance to keep modules decoupled and easier to evolve.

Frugality Principle

Write the smallest program that works; avoid unnecessary code bloat.

Transparency Principle

Design should be visible and debuggable; clear variable and function names aid comprehension.

Common‑Sense Interface Principle

Avoid overly clever or unconventional APIs that increase learning cost.

Silence Principle

Log only essential information; excessive logging obscures real problems.

Remedy Principle

When an exception occurs, abort early and provide sufficient error details.

Concrete Practices for Golang

Enforce code formatting strictly.

Limit files to 800 lines; split when exceeded.

Limit functions to 80 lines; refactor when exceeded.

Restrict nesting depth to four levels; use early returns.

if !needContinue { doA(); return } else { doB(); return }

Early returns decouple logic branches.

Mainline Development

Keeping review changes under 500 lines ensures thorough review and reduces the burden on reviewers.

Recommended Reading

Read "The Art of Unix Programming" and "Software Engineering at Google" to deepen engineering thinking.

Call to Action

Join the architecture community for further discussion and sharing.