Evaluating Code Quality: Definitions, Readability, Maintainability and Practical Guidelines

1. What Is Good Code

The first step is to understand what constitutes good code. The author tried to define "excellent", "good" and "poor" code, but most definitions lack concrete operability.

1.1 Definition of Good Code

Quotes from well‑known experts:

Bjarne Stroustrup (C++ creator): Logic should be clear, bugs hard to hide; dependencies minimal; error handling follows a clear strategy; performance close to optimal; code does one thing.

Grady Booch (author of "Object‑Oriented Analysis and Design"): Clean code is simple, direct, reads like good prose, reveals the designer's intent with minimal abstraction and clear control flow.

Michael Feathers (author of "Working Effectively with Legacy Code"): Clean code looks like it was written by someone who cares about quality, has no obvious improvement points, and shows that the author considered all aspects.

These definitions are reasonable but hard to apply directly, especially for newcomers who struggle to interpret "simple and direct" or "no obvious improvement needed".

1.2 Readable Code

Readability is prioritized because a programmer prefers a buggy but understandable codebase over a flawless but unreadable one.

1.2.1 Word‑by‑Word Translation

The author suggests translating code line‑by‑line into natural language, then reading the translation aloud to another person. If the listener understands, the code’s readability is considered adequate.

1.2.2 Following Conventions

Adhering to coding style guides (e.g., Google Style) and project‑level conventions reduces maintenance cost and improves communication.

1.2.3 Documentation and Comments

Documentation should be findable and understandable within minutes. Typical docs include project overview, quick‑start for newcomers, and detailed API specifications. Comments inside functions should explain non‑obvious decisions, not restate the code.

1.2.4 Recommended Reading

"Clean Code" by Robert C. Martin

1.3 Deployable Code

Newcomers often miss exception handling, concurrency, performance, and logging considerations.

1.3.1 Exception Handling

Robust code must anticipate server crashes, network timeouts, malicious inputs, etc. Unit‑test coverage below 50% usually indicates insufficient exception handling.

1.3.2 Concurrency

Concurrency bugs are common. The key is protecting shared resources, avoiding unsynchronized access, and being wary of hidden ordering dependencies.

1.3.3 Performance Optimization

Performance should be measured, not guessed. Two code‑level indicators are algorithmic time complexity and costly single‑step operations (e.g., DB or I/O access).

1.3.4 Logging

Effective logs record every exception, external call, and critical path point, with clear, consistent messages and sufficient context for troubleshooting.

1.3.5 Further Reading

"Release It!" – Design and Deploy Production‑Ready Software

"Numbers Everyone Should Know"

1.4 Maintainable Code

Maintainability is judged by future impact: can the code survive the original author’s departure and evolving requirements?

1.4.1 Avoid Duplication

Both module‑internal and module‑external duplication indicate poor skill. Modern IDEs can detect duplicate code automatically.

Example of duplicated code (original):

if (memberList.size() > 0 && memberList.size() < 200) {
    // return current member list
    return memberList;
}

Later versions become more tangled with additional conditions and comments, illustrating how duplication and unnecessary comments degrade readability over time.

1.4.2 Module Partitioning

High cohesion within modules and low coupling between them is essential. Large classes (>2000 lines) or functions spanning multiple screens signal a design problem. Excessive dependencies or circular dependencies also hurt maintainability.

1.4.3 Simplicity and Abstraction

Simple, elegant code avoids unnecessary complexity. Experienced developers abstract core ideas and keep implementations concise, allowing the codebase to evolve from complexity back to simplicity.

1.4.4 Recommended Reading

"Refactoring" – Improving the Design of Existing Code

"Design Patterns" – Elements of Reusable Object‑Oriented Software

"Software Architecture Patterns" – Understanding Common Architecture Patterns and When to Use Them

2. Conclusion

The article presented various objective and subjective methods for evaluating code quality. While the criteria are not exhaustive, they provide a starting point for developers to improve their "taste" for good code through continuous learning and critical thinking.

The next article will discuss concrete ways to improve personal code quality.

3. References

Why Every Team Has Lots of Bad Code

Weibo Distributed Storage Exam: Case Study and Exercises

Weibo Docker‑Based Hybrid Cloud Platform Design and Practice