[Review/Book] The Art Of Readable Code — 1. Surface-Level Improvements
How Long Should A Name Be?
Whether you’re naming a variable, a method or a class, a lot of information can be conveyed into what you make, even though there isn’t much room. Some specific principles apply to pack as much information into your names as possible, most of which are already commonly accepted to programmers. For example, it would be better to use specific and concrete words like Fetch or Download , instead of Get , when your method is intended to retrieve a page from a local cache, from a database, or from the Internet?
Also, you need to avoid generic names like tmp , res or retval , which is usually cop-outs that mean “I can’t think of a name.” As these names don’t pack much information, pick a name that describes the entity’s value or purpose, instead.
These tips are implicit constraints that many programmers agree with. Back to the question I’ve raised on the title, how long should a name be if we say that it include information about the source code we write? Generally, the longer a name is, the harder it is to remember, and the more space it consumes on the screen, possibly causing extra lines to wrap. The authors bring a nice metaphor that fits right in this case.
When you go on a short vacation, you typically pack less luggage than if you go on a long vacation.
Similarly, identifiers don’t need to carry as much information in a small ‘scope’ so that you can get away with shorter names because all that information is easy to see within a line, a method or a class. If it is a class member or a global variable, however, it would be much less readable without further explanation.
Why does substring() use exclusive ranges?
While trying to make clear and unique names to contain many information, you might be missing the fact that they can sometimes be misunderstood. Someone could do wrong interpretations from the names and you need to actively scrutinize them. One of the most typical problems regarding this is using inclusive / exclusive ranges in a method.
print getDataRange(start=2, stop=4)Here is an example where you can’t tell if it’s “up to” or “up to and including”. Does this print data from the range of [2, 3] or [2,3,4]? we know that this will start from the second index but don’t guarantee that the fourth data be brought up. Commonly used is first/last for inclusive ranges containing the last index.
How about exclusive range where a method only selects data until before the given last index like [2,3] in the example? In practice, you may want to print all the events that happened on October 16. Which one do you prefer?
// Exclusive Range
PrintEventsInRange("OCT 16 12:00am", "OCT 17 12:00am")// Inclusive Range
PrintEventsInRange("OCT 16 12:00am", "OCT 16 11:59:59.9999pm")
Of course, you will prefer the former method since it’s way easier to use. The typical convention for naming an exclusive range is begin(start)/end. Take a look at the documentation of programming language you are using and see if it really follows the convention. So do Javascript and Java, at least.
With the range issue, there are many source code that can be misconstrued. when it comes to naming a boolean, for instance, adding a prefix like is or has helps to make it clear that it’s a boolean. In short, I recommend you to play devil’s advocate and imagine how your name be misunderstood before deciding on it. The best names are resistant to misinterpretation.
What code is aesthetically pleasing?
Good source code should be just as “easy on the eyes”. Some developers have a tendency to make light of making code look more consistent. They regard the current issues they are working on as too urgent to align columns with, add enough spaces and pick a meaningful order for their code. However, it doesn’t take as much work as they fear and it would be way easier and faster to read.
One technique to note here is to rearrange line breaks and line up the comments. This code has a nice consistent pattern, and is easier to scan through. You could improve it by moving all the comments up with one line so that the information is lined up in a more compact table like the one written below.
Conclusion
Refactoring your code in surface-level is important not only for the quality of code but for the cooperation with your teammates. We’ve discussed many skills to help you improve the readability of code. In your project, you may now feel that your team has been using the “wrong” style. Nonetheless, this book suggests to follow the original convention rather than to attempt to change the whole things in a day because ‘consistency is way more important than rightness.’ You need to think of how to adapt the “right” style into the project gradually.
