1. Stop Naming Variables X and Y
X = 10 tells me nothing. In a week, you won't remember if X is a user’s age, a coordinate, or the number of times you've contemplated quitting.
The Fix: Use descriptive names. user_age_years = 10 is self-documenting.
2. Comments are for "Why," Not "What"
If you find writing comments tedious, it’s because you’re likely explaining what the code does (which the code should do itself).
The Fix: Use comments to explain the intent. Raise your Comment Density to help the "future you" understand the logic behind that weird edge-case fix.
3. Don't Build a Code Maze (Cyclomatic Complexity)
If you have five if statements and three for loops nested inside each other, you haven’t written a function; you’ve written a labyrinth.
The Fix: Break the "maze" into smaller, controllable functions. If it’s hard to test, it’s too complex.
4. Treat Your API Keys Like Your House Keys
We’ve all thought, "I’ll just hardcode this API key for a second and delete it before I push." The Reality: You will forget. You will push it. And even if you delete it later, Git History is forever.
The Fix: Use .env files and environment variables from day one.
5. Be a Ruthless Eraser
"I'll leave this block here... I might need it later." No, you won’t. Dead code and unused libraries are "digital clutter" that confuses your team.
The Fix: Don't be afraid to delete. That’s what Git history is for!
6. Global Variables are a Trap
Global variables seem handy until a random function 300 lines away changes one by accident, and your whole app collapses.
The Fix: Keep data scoped inside classes or functions. A controlled state is a predictable state.
7. Beware of "Spaghetti" Coupling
Ever changed a line in your Login logic only to have the Shopping Cart break? That’s high coupling.
The Fix: Aim for independent modules. A change in one area shouldn't cause an avalanche across the whole application.
8. "It Works on My Machine" is a Red Flag
If running a simple test requires 3 databases and 5 APIs to be live, your code has low testability.
The Fix: Use Dependency Injection and Mocks. Pass functions as parameters so you can test logic in seconds without needing the entire infrastructure.
9. Composition over Inheritance
Deep inheritance (a class inheriting from a class, which inherits from a class...) is a nightmare to track.
The Fix: Prefer breaking behavior into small components. It gives you more control and prevents "backfire" changes.
10. The "God Class" Delusion
A "Helper" class with 30 unrelated methods isn't helpful-it's a mess.
The Fix: Low cohesion makes testing impossible. Refactor into smaller classes with a single responsibility each.
11. Aim for High Cohesion
If the methods inside your class don't actually work with each other, they shouldn't be in the same class.
The Fix: High Cohesion = Clear Responsibilities = Fewer Bugs.
12. Watch Your Code Density
Sometimes code "reads heavy" even if it’s short. Too many actions crammed into a few lines make the logic opaque.
The Fix: Clarity > Brevity. Don't sacrifice readability to save three lines of space.
13. Measure the Halstead Difficulty
This metric measures how hard it is to understand and modify your code. If the difficulty is high, the "mistake probability" skyrockets.
The Fix: If you look at a block of code and feel like moving one piece will break the world, it’s time to refactor.
14. The Ultimate Metric: Maintainability Index
Code isn't judged by whether it works today. It’s judged by how easily it can be fixed tomorrow. The Takeaway: A high Maintainability Index (combining complexity and size) means less stress for you and your team.
Top comments (1)
This is spot on. I couldn't agree more about the importance of coding standards. Just like Google has its style guides, in the Chinese Java world, we heavily rely on the 'Alibaba Coding Guidelines'. Even though it's specific to Java, the concept applies everywhere: a clear handbook is essential for passing code reviews and keeping code clean.