What is quality code?
Why spending time on quality matters
Being a developer, you’re often caught in the middle of “get it done so we can ship” and “do it right so that we don’t have problems later.” It’s a fine line to walk and there’s arguments on both sides. You have an extraordinarily successful entrepreneur, Reid Hoffman, saying:
If you are not embarrassed by the first version of your product, you’ve launched too late. — Reid Hoffman
But then you have a truly competent developer, the very creator of BitTorrent saying:
Things which any idiot could write usually have the quality of having been written by an idiot. — Bram Cohen
So which is it? Is shipping the code important? Is having really solid code important? The answer is: yes. Both are important. But the latter often gets overlooked. As a result, I’ve taken it upon myself to come up with some really quick things to watch out for when coding to help improve quality.
Bad Code
If you want to write good code, first you have to identify what bad code is. Just taking a look at the code shown here, we can already spot a few issues with it.
It’s hard to pinpoint exactly what makes it bad, because there can be so many things. But there are general trends. To identify bad code, simply use the Elephant Test. Put simply, the Elephant Test is akin to saying something is “difficult to describe, but easy to recognize.” After writing software for over a decade, you get a feel for what “bad code” actually is.
Very Long Files
It happens to the best of us. You need to add a check to see if some parameter is less than some threshold, so you find where that logic is and you take on a few lines to do what you need to do.
Another developer comes in and needs to mess around in that section as well, but she makes the smart move and refactors it so that there’s a separate function in the file to handle the filtering logic.
Since you’re dealing with “users” any way in this file, it makes sense to add a function to the end that hashes passwords. Maybe you’re doing things with OOP, so adding functions to this class makes sense. But the end result is you have a file that’s over 5,000 lines and now impossible to read.
Don’t do this. Set a rule for yourself or your team. No files should be longer than 250 lines. Or 100, if you’re ambitious.
Huge Functions
After reading the previous section, you’ve managed to keep all of your files to less than 250 lines. Woo hoo! But now each of those files is really just one big function. That’s another distinct smell of “bad code,” in my opinion. Of course, the need will arise to have large functions from time to time, but they should be the exception that justify the rule. There are very few legitimate reasons to have a function that’s hundreds of lines long. You’ve seen them. In fact, you may have even written them. I know I have. But it’s a pain for the next developer to go in and try to make sense of what the parseText function is supposed to do when it’s 712 lines.
Maybe another rule is needed here. This one will be HIGHLY language specific, but whatever it is, set a rule. No function should be more than 100 lines. Or whatever makes sense.
Tabs vs Spaces
This debate has raged on for as long as the TAB key has existed. The answer is “spaces.” But if you MUST use tabs, use them and make sure everyone else in your team does.
Large Blocks of Commented Out Code
This usually happens because developers are generally well intentioned. A developer has to make significant changes to something and sees existing code that maybe might do something. He doesn’t want to outright remove it, so he’ll comment it out “in case anyone needs it later.” Three months later, no one knows what that code was for or why it’s there. If the code doesn’t need to be there, then don’t have it there.
Duplicate Code
Everyone tries to avoid this, but it happens nonetheless. It’s best to avoid.
Duplicate Code
Everyone tries to avoid this, but it happens nonetheless. It’s best to avoid.
Duplicate Code
Everyone tries to avoid this, but it happens nonetheless. It’s best to avoid.
Good Code
Generally speaking, anything that is not “bad” is “good.” Specifically when talking about code quality. You don’t have to do any specific good thing, just avoid doing bad things. I’ve found a good way to do this is the three soundsLike(‘r’) of Coding Standards.
Written
If you’re going to have these rules or coding standards, make sure they’re written down. Use a wiki, spreadsheet, README.md, Google Doc or whatever. Just make sure your coding standards are written. Remember however, this document is living — so it can and should change frequently.
Reviewed
There shouldn’t be even one line of code that hits your main repository unless another pair of eyes have seen it. There’s different workflows to accomplish this — Pull Requests, formal code reviews, and so on. Even if you’re a lone developer, institute a Pull Request-like system and give yourself a few hours after making the code change before you review it. You’ll be surprised what even you will catch against yourself!
Refactored
A few weeks ago I was having a conversation with someone about this concept. The question was “what do you do when your boss says you have to just ‘get it done by Friday’ and you know it’s poor quality?” My answer is to ‘just get it done’ but negotiate time after Friday to go back and fix it. Non-technical managers (and even some technical ones) have a hard time justifying time to refactor code or even optimize it. This is a crucial component to writing quality code.
Writing for me is largely about rewriting. — Khaled Hosseini
Coding has the same truth. When you write something the first time, it may work, but maybe it’s a bunch of duct tape and bubble gum holding it together. Refactoring is critical to replacing that with something better.
Conclusion
I hope this has been helpful to at least someone out there. Please leave comments wherever appropriate and I’d love to hear how you maintain a good, solid codebase.
About the author: Shamoon Siddiqui is a serial entrepreneur, software developer, investor and public speaker in the NYC area. To get more awesome content like this, just sign up for my mailing list.
