There’s lots and lots of software code in the world these days; heck, Google alone has more than two billion lines of code in its repository. But not all source code is created equal. Software developers usually have strong preferences as to what makes some raw code “good.”
To find out what makes the code behind some software better than others, I consulted a handful of longtime software developers. I also scoured online discussion forums to see what characteristics other programmers expect or want in the code they write and have to work with.
Based on that input, here are six generally agreed upon characteristics of “good” software source code.
1. It’s easily readable
Developers seem to agree that one of the most important qualities of code is its readability. Code that’s written in a way that makes it easy for other programmers to understand with a minimal amount of time and effort is considered top notch.
“I feel that if I can’t understand the author’s intent in 5 minutes or less, the coder did a bad job,” said Luke Burnham, a senior software engineer at Lionbridge. “The computer doesn’t care about variable names or line spacing but people do. Code is written once but read hundreds of times over its lifetime. Using meaningful variable names and injecting spaces in order to increase the readability of the code will make code better.”
An anonymous senior web application developer with more than a decade of professional programming experience also recommended to me that writing good code means, “Following a consistent coding style (proper spacing, indentation, general flow).” He also emphasized the importance of choosing “Variable names that make sense.”
“Wrap Early, Wrap Often,” is the personal policy of Neil Best, a senior application developer at Gogo. “This may be a personal preference / style thing, but I go for tall over wide, not to inflate my line counts but actually to increase legibility,” he told me. “If a function has two arguments put them on two new lines. If an arithmetic expression has many terms give them each their own line. Your interpreter may require you to use trailing operators (RTFM) but it's worth it.”
In short, more readable equals more understandable which makes everyone’s life easier.
“The faster someone can look at it and understand it. The faster the application will move forward (feature and revenue),” said commenter Glennular on Stack Overflow. Or, as Stack Exchange user mojuba put it, “There is really no good criteria other than how fast you can understand the code.”
2. It’s well commented
In addition to good formatting and naming, comments can also make code, ultimately, more easily understood. But not just any comments, as Burnham pointed out. “I don’t need comments to tell me what a For loop does. I need comments to tell me WHY the code is doing what it is doing,” he said. “I think good code has comments that explain what’s in the author’s head as the code is written.”
As Best said, good commenting can help not just other developers who have to read your code, but also yourself. “Be kind to your future self who has no memory of what you are thinking at this moment,” he said. “Even if you are the only one who will ever inspect or modify your code in the future you can make things easier on yourself by choosing meaningful names and adding informative comments. I have actually embraced the literate programming paradigm to go beyond sprinkled, terse comments to interleaving prose with code to document what is going on.”
Kevin Moylan, a senior software engineer at Genuine Interactive, summed it up simply: “Comments are huge.”
3. It’s simple
A piece of source code may ultimately be doing complex things, but the best code, developers often say, is often very simple. Good programmers will know how to get the job done without over-complicating things.
Moylan explained to me via email that, “Each bit of code should do one job, do it very well, and allow for the next bit of code to do the next job. The best solutions are the simplest solutions.”
The anonymous web developer I spoke with cautioned against “duplicating too much code.” He also recommended, “Short well defined functions that perform one task well” citing one 1,000-line function he had worked with which was a nightmare to manage.
Otávio Décio echoed this on Stack Overflow, writing, “Each function does exactly one thing,” while user mhomde advised on Hacker News “... no blob classes or methods with an infinite number of purposes. Each layer of abstraction simple enough to keep in mind in its entirety.”
Burnham also emphasized the importance of simplicity, noting, “I tend to borrow from Thoreau when writing code: Simplify, Simplify. In every possible way. I can’t stress this enough.” He also add that good code is not only simple, but even lazy. “Good code only does the minimal amount of work,” he told me. “I’ve seen lots of code that does all sorts of work and then quits because of simple test that could have been done at the outset.”
In the end, most developers believe that keeping things simpler will ultimately make for better software As Quora user Neville Kuyt said “... there's a proven statistical correlation between code complexity and bug counts….”
4. It’s flexible
The functionality of an existing piece of code will often need to be changed, expanded, or reused elsewhere in the future. That’s why Burnham advised that, “Good software is written with both today’s requirements and tomorrow’s expectations in mind.” Obviously, predicting the future is impossible, he noted, but added “I can write software today that is flexible enough to require only minimal changes to accommodate the changes in future requirements.”
Code is good if future developers will be able to “add or change certain parts of the code without having it break other parts of the code,” the anonymous web developer told me.
Kristopher Johnson wrote on Stack Overflow that “You don't really know how good someone's code is until you try to change it.”
Stack Exchange user Michael Riley wrote that ultimate sign of good code is when “The brand new guy/gal was just told to make modifications to a system you built 6 months ago and he/she never once asked you a question”
5. It’s maintainable
No matter how well a piece of code is written, it will, inevitably, still have bugs. “Obviously somebody may have to fix it,” Moylan told me. “Make it easy for that person, it may be you.”
Maintainability, then, is a key attribute of good code. “All code has to be maintained: no need to have that task made more difficult than necessary,” user gbn wrote on Stack Exchange.
Avoiding doing things like “hardcoding values that can change (urls, access keys, database passwords, etc),” the anonymous developer told me, can make future maintenance easier.
“What makes the difference between working code and great code is maintainability.” David Rachamim wrote on Quora.
6. It works
Finally, there’s one seemingly obvious characteristic of good software code that should probably still be stated, which it was by the anonymous web developer I spoke with. “It needs to work,” he told me. Moylan seconded that, saying “First of foremost, it has to do the job it was designed to do.”
Burnham, though, summed it up all simply: “No matter how great it looks, if it doesn’t do the job, it’s no good.”
This story, "6 things all good software code has in common" was originally published by ITworld.