Where technology meets something or other

What makes good code

Got an email recently asking: “What makes good code?” I was a bit sick at the time, so I rambled the following off the top of my head as quickly as I could before taking some Advil, decongestants, and expectorants and then lying back down. Now, in somewhat better health, I thought I’d share these thoughts because I feel they’re an interesting starting point for an important discussion. At the time, I wrote:

It’s probably easier to ramble by phone because I’m currently under the weather but off the top of my head, here you go:

Good software code doesn’t just compile, it communicates. It talks to you as a developer here and now and to future you, who will be maintaining this code. It is comprehensible to your team and to anyone who will look at it externally.

It always chooses reliable and testable over clever, and prefers to take an extra step or ten if needed to make its intent and outcome clear.

It’s code that thinks about scale, about living in a forest as well as being a single tree, and being run a million times at once as well as once.

It’s code that believes in being broken down into sensible units instead of massive single implementations.

It’s code that understands that it will be implemented not once or twice but reviewed and refactored to be the best and most robust implementation possible.

It’s code that thinks globally and provides hooks for many cultures and multi-abled users, which is a real code-level thing — how you add internationalization and accessibility and not as an afterthought.

It’s code that thinks about not just the specifics of the destinations it will run on today but how to adapt for when those destinations change over time.

That all said, what are your feelings on what makes good code and what would you add to, remove from, or modify in my initial list? I’m looking forward to hearing what you have to say.

Anonymous suggests: It’s code that ships. Good code works, does what I need, is delivered on time, and the rest of these points be damned.

Dave DeLong: Great code leaves you in awe and inspired to go write your own great code.

Paul Cantrell: It’s code that strikes a mindful balance in all the tradeoffs these other bullet points imply. It sees engineering tradeoffs, not dogmatic absolutes. It doesn’t let tools or techniques become in-group status markers.

Rainer Brockerhoff: It’s code that I can easily reuse (often years later) and which can be extended/adapted in a few lines.

Anonymous overstates it, but they have a point: sometimes quality is more important, sometimes urgency. Some code needs room to grow, some doesn’t. Some code will have a long life, some will have a short life.

Good code knows its purpose, understands the problem it solves and the human context in which it is solving it, and strikes the right balance between getting something working now and avoiding technical debt. That balance is never quite the same from project to project.

Good code is obvious, well-named and doesn’t need many comments to explain how it works. Comments are more about explaining why the given approach was used or references to other sites/documentation than explaing how the code actually works, which shouldn’t need explanation. If it does, your variables/methods probably aren’t named well or your methods/classes are trying to do too much and should be broken into smaller components.

“Clean Code” by Robert Martin is required reading imo. I really struggled to understand why one approach was better than another until I read that book. It has tons of examples to back the “philosophy” of clean code.