Quality Code: How do you judge?

[Originally published on the Open Source Small Business blog, in January 2008.]

I’ve seen a lot of code in various languages. As a technical writer, I used to write documentation for programmers teaching them how to use a particular interface or system. I’ve been involved with traditional software development projects at large software companies and startups. And I’ve done my share of actual programming of web applications.

I’m finding there are several indicators I look for when evaluating code, specifically for PHP, our language of choice. I’ll go in more depth on each of these qualities in future posts, but for now just thought I’d capture them while they’re fresh in my mind. So when I review code of a web application, here are some qualities I’m looking for:

• Secure. Does the application trust users to provide good data? Does it protect its internals to prevent all the various types of exploits out there? Does it protect data from malicious users?
• Fast. This could mean many things, but I’m looking for efficiency across layers. Is there a database call inside a loop that gets called a couple hundred times? That’s a huge speed killer. I look for code that has an appropriate level of abstraction to the size of the problem–and makes sensible choices about how much data to load for each request.
• Powerful. This one is stolen from Paul Graham. Does the code use object-orientation and inheritance in a powerful way? I like seeing utility methods on base classes, which can then be leveraged to make very short, easy-to-understand final classes. Are the methods attached to the appropriate level of the class hierarchy? How short can you make the main logic of the application?
• Clear. Going hand-in-hand with power, clarity is about making it apparent what each chunk of code is for, and how to go about changing it to make it work the way you want. Clear code is maintainable, well-documented, easy to customize.
• Customizeable. Was the program designed in a way that’s easy to override, easy to customize, easy to run in other environments? Can it be managed effectively, and work broken up into different units?
• Reliable. Does each function or method cover all possible scenarios? Is there proper error-handling in the code? When an end user hits upon some combination of things that the programmer never anticipated, does the program die ungracefully, or provide useful feedback?

Very few programmers hit all of these. My biggest weak area is the reliability one–after reviewing other people’s code, I find a lot less exception handling in my code. We’ve all got something to learn. But reviewing other people’s code can help you spot weaknesses in your own, and develop a much stronger sense of how to do it right.