Ten Rules for Good Code

pieterhpieterh wrote on 22 Sep 2015 15:55


It's one of my interview questions: "what is Good Code?" Surprisingly, almost no-one gets it right. It's not about speed, elegance, language, or style. Good Code is code that solves real problems for real people, in an effective way. Let me list the top 10 rules for writing good code.

0. Use Git and Github

I'm not going to dignify this with a non-zero number. If you aren't using git and github.com then you are already making excuses for doing it wrong. It is not about fashion or groupthink. Github (the company) know how to make Good Code, and their tools reflect this.

1. Use Problem-driven Development

Identify the next single smallest problem you want to fix. Write the simplest plausible solution, and test it. Your commit message states the problem, and then your solution. If there is a single change you make to how you code, please, this one. Don't make features. Solve problems.

2. Make it Open Source

Not eventually. Not when it's working. Not if you get management approval. Now, today, before it's finished. Before you even decide what you're making. Before your first commit, even. Open source means people, and that means voices to guide you to solving the right problems.

3. Always Be Making APIs

Write every piece of code as the body of an API. Read my Ten Rules for API Design. Be generous with new repositories. Layer your projects like you're making lasagna. Document your APIs, use them, publish them.

4. Don't Document the Code

Documenting code is like writing "Tasty!" on the side of a coffee cup. If the code isn't readable on a grey Monday morning before coffee, chuck it out and start again. What you document are APIs, so that can mean methods and classes. That is fine. Explaining what this funky loop does is not fine.

5. Style for Readability

You do need a style guide. And it must be strict. All that matters is readability. Collect patterns that work in your language. Document them, improve them, and make sure the entire codebase conforms. Do not use automatic reformatters, as they hide mischief. A good style is worth applying by hand.

6. Better is the Enemy of the Good

We already know this yet it's worth repeating. Do not optimize your code. Aim for "OK" and then stop. If you are following rule #1 then slow performance will pop up as a juicy problem somewhere down the line. It will always, always, be in a place you never thought of.

7. Use Your Own Work

It's shocking how many programmers don't use their own work. Then they have the arrogance to lecture users about "what they really need." Look, if I brew beer and make pizza, then I'm damn well going to sit at my table. Good Code is so delicious you can't resist it.

8. Use Code Generators Carefully

Code generation is powerful stuff. I'm speaking of industrial-scale tools like GSL. If you don't use it, you're handicapping yourself. If you over-use it, you get insanity. Learn to look for the sweet spot where it's simple and obvious.

9. Make Portable Code

When you have to get into system internals, hide these behind abstract APIs. Your code should run on every box there is. If it doesn't, then invest in portability frameworks. This always pays off. Portable code is always simpler and cleaner than the weird stuff that thinks it's special because it does voodoo.

10. Lie to Your Management

Maybe you have an enlightened management that knows what "open allocation" means. Or maybe they're going to be one of your main problems. When they demand schedules, plannings, designs, and architectures, lie to them. If you cannot do this, find someone who can. It is easier to get forgiveness for success than permission.

I want to dedicate this list to Leif Svalgaard, possibly the best programmer in the world, who taught me most of these rules in my first ever real job.


Add a New Comment
Unless otherwise stated, the content of this page is licensed under Creative Commons Attribution-ShareAlike 3.0 License