12 Coding Anti‑Patterns That Destroy Readability (And How to Spot Them)

A senior architect shares twelve coding habits that severely hurt code readability and make maintenance a nightmare, using a fictional programmer "Er Gou" to illustrate each anti‑pattern.

1. Over‑splitting services: one table per microservice

Er Gou enthusiastically applies microservice principles, creating a separate service for every database table. While this seems to improve isolation, it leads to a sprawling architecture with dozens of services, massive RPC overhead, versioning chaos, and a painful deployment process for newcomers.

2. Refactoring without releasing to production

Er Gou adds a new logic flag and claims the refactor improves performance, but only enables it in the test environment. When the flag isn’t turned on in production, a teammate unknowingly modifies the new logic, causing failures that are hard to debug.

3. Writing excessively long methods

Believing that longer methods are more coherent, Er Gou writes functions that exceed a thousand lines, never extracting smaller helpers. This makes the code hard to understand and slows down anyone who inherits the code.

4. Deep nesting of if/try/else blocks

Er Gou nests conditional and exception blocks more than ten levels deep, claiming the code has "no bugs". New developers are overwhelmed by the complexity and struggle to follow the logic.

5. Random, meaningless variable names

Preferring artistic freedom, Er Gou names variables arbitrarily (e.g., str1, list2) without reflecting business meaning. He can remember them initially, but months later the purpose is forgotten, hindering maintenance.

6. Writing misleading comments

Er Gou deliberately inserts incorrect comments, swapping true/false statements or swapping unrelated notes, leading reviewers to waste time trying to decipher the intended behavior.

7. Updating code without updating comments

After extensive code changes, Er Gou never updates the existing comments, leaving them out of sync, partially correct, and often misleading for anyone trying to understand the implementation.

8. Blindly copying code

In a hurry, Er Gou copies and pastes code blocks throughout the project. When a teammate modifies one instance, they forget to update the others, resulting in duplicated bugs and endless debugging.

9. Writing detailed technical proposals but ignoring them

Er Gou spends a lot of time drafting comprehensive design documents, yet during implementation he shortcuts and chooses simpler, less reliable solutions, causing a mismatch between the design and the actual code.

10. Refusing to add logging

Confident that his code never fails, Er Gou never adds logs. When a production incident occurs, the lack of logs makes root‑cause analysis extremely difficult, leading to prolonged outages.

11. Introducing heavyweight frameworks for trivial problems

Er Gou learns advanced rule‑engine frameworks (Drools, SPEL) and integrates them to solve a simple strategy‑selection problem, adding unnecessary complexity and a steep learning curve for the team.

12. Reinventing the wheel for common problems

Instead of using proven libraries (e.g., Redisson for distributed locks), Er Gou builds his own solution with SETNX. The custom implementation eventually fails, but he treats it as a learning experience.

Conclusion

These twelve practices—over‑modularization, excessive refactoring, massive methods, deep nesting, poor naming, misleading comments, stale documentation, code duplication, ignored designs, lack of logging, unnecessary framework adoption, and wheel‑reinvention—significantly reduce code readability and increase maintenance difficulty. Avoiding them leads to cleaner, more maintainable software.