What is good code?
Having only been a programmer for a little over two months now, I worry a lot about whether or not I am writing “good code.” Recently, I was refactoring an old project, and I realized that I don’t have much of an idea of what “good code” is. As a beginner, I tend to think of “good code” as code that follows principles such as DRY, single responsibility, etc., but I was curious about what professional developers thought.
So, I scoured the internet for some answers, and (surprise!) there are many different opinions about what makes code “good.” Some developers want code to be testable, but others think testing is a waste of time. Some want efficiency, others don’t care.
However, one common theme tying together all the surprisingly passionate opinions was readability. According to one “pseudo-scientific” study in which developers were asked to answer the questions, “What do you feel makes code good? How would you define good code?”, the most common answer was that the code has to be “readable” (78%). The second most common answer was that the code must be “testable/tested” (29%), and, tied for the third most common answer, the code must be “simple” and it should “work” (25%).
So, why is readability so important? Many people pointed out that most developers spend much more time reading code than they do writing code. That has certainly been my experience; for every new feature that I add to a project, I probably read hundreds of lines of other people’s code to figure out how to implement it. Along with that, I have certainly dealt with the frustration of reading (or trying to read) badly written code; while it is difficult to define what good code is, it is certainly not difficult to know when you are dealing with bad code. This diagram represents it well:
As such, code in most contexts is about communication, and your target audience is not the computer but other programmers and yourself. Most of the time you will be working with a team, and you will be working with somebody else’s code.Writing code that is easy for other programmers to read will make the project easier to change and easier to extend, all while making mistakes less likely.
So for the purposes of making this blog post useful, I will go ahead and make the assumption that “good code” is code that is readable. So now the question becomes: how do I write readable code?
Here are a few of the most helpful tips that I found:
Use variable and method names that make sense
- Use names that are pronounceable and intention revealing
- Be consistent and use one word per concept. For example, .map and .collect in Ruby do the same thing, but don’t use .map in one class and .collect in another
- Use verbs for function names, and nouns for classes and object attributes
Make functions functional
- Make functions concise, and try to have as few arguments as possible
- Functions should only do one thing; if a function does too many things, try breaking it down into smaller functions (which should also reduce the number of arguments required per function)
- Functions should only do what the name of the function suggests. Again, if the name of a particular function is not descriptive of what it does, try breaking it into smaller pieces, with each function name clearly describing what it does.
Use comments sparingly
- Use comments for emphasis or to explain your intention
- You should not need comments to explain what the code is actually doing; if you have to use comments to explain what a function is doing, then rewrite it
- Use comments to warn of the consequences of using a particular method or function. For example, “this method takes a long time to run.”
I must admit that after writing this blog post, I feel a lot more confident in my ability to write what most developers consider to be “good code.” I tend to think that there is a right way of doing things for most problems, and I often worry a lot about whether my solution is too long or too inefficient. However, I like the idea that my code should speak for itself — it makes writing code like writing a story, and the idea that another developer might enjoy reading my code is pretty exciting.