Readability - Julio Merino (jmmv.dev)

Readability: Series wrap-up

That’s it! After two months worth of posts, it is time to part with the the readability series. We have covered a lot of ground with these 14 posts: from mundane things such as blank lines and spelling to deeper topics involving dictionaries and global state. Before some parting words, here comes the full list of posts on this series. This is your time to catch up with any posts you have not yet read!

August 1, 2013 · Tags: <a href="/tags/readability">readability</a>
Continue reading (about 2 minutes)

Readability: Narrow try/catch blocks

Try/catch blocks (or try/except, or whatever they happen to be named in your favorite language) are the mechanism by which you capture exceptions raised by a chunk of code in a controlled manner. Within that chunk of code, it does not matter which line throws the exception: any exception specified in the catch statement will be captured, and it is “impossible” to know at that point where it originated. Consider this piece of code:

July 29, 2013 · Tags: <a href="/tags/readability">readability</a>
Continue reading (about 3 minutes)

Readability: Don't modify variables

Single assignment says that a variable should only be assigned a value once; i.e. a variable should only be initialized and never modified later. This could be said to be a property of functional programming—never mind that it’s used in compiler optimization a damn lot—so it may sound a bit out of scope in a readability post. Not really. When you force yourself to avoid modifying already-defined variables, you will need to find other ways to express your intent. To do so, in general: you will use a high-order construction instead of a loop; you will end up having to define intermediate variables, each with its own descriptive name; or you will move pieces of the code to an auxiliary function, also with a descriptive name.

July 25, 2013 · Tags: <a href="/tags/readability">readability</a>
Continue reading (about 4 minutes)

Readability: Conditionals as functions

Conceptually, there are two kinds of conditional statements: ones that compute—or affect the computation of—a value and others that guard the execution of optional code (e.g. functionality enabled by a command-line flag). In this article we will focus on the former kind. One way to think of those conditionals is as if they were to represent functions, just written inline. In other words: while it should be possible to move the conditional statement to a separate function, it has not been done because the algorithm is simple enough to not warrant it.

July 22, 2013 · Tags: <a href="/tags/readability">readability</a>
Continue reading (about 3 minutes)

Readability: Explicitly state complementary conditions

In the most basic form, a conditional has two branches and the conditional expression inspects a single variable on entry. For example: if balance >= 0: color = BLACK else: color = RED In this little code snippet, the condition balance >= 0 only depends on one variable, and the two branches of the conditional cover all possible values of the input variable. I.e. the first branch covers all cases where the balance is positive or zero, and the second branch covers all cases where the balance is negative. The balance variable cannot have a value not covered by these cases. Easy.

July 18, 2013 · Tags: <a href="/tags/readability">readability</a>
Continue reading (about 3 minutes)

Readability: Do not abuse classes as global state

You know that passing state around different functions by using global variables is bad: it results in spaghetti code, it introduces side-effects to your functions and, well, is just bad practice. Then: don’t make the same mistake when using classes. The form this manifests in code is by having a particular class method (not necessarily the constructor!) initializing a member field and later having other unrelated methods querying the attribute “out of the blue”.

July 8, 2013 · Tags: <a href="/tags/readability">readability</a>
Continue reading (about 3 minutes)

Readability: Dictionaries are not data types

Yes: a dictionary is a data type. No: a dictionary is not a way to implement abstract data types; doing so is lazy programming and is asking for trouble later on. What do I mean by this? In Python and other similar dynamic languages, dictionaries are a mapping of keys to values that have no typing restrictions: the dictionary is heterogeneous, and a single dictionary can contain elements of different types both as its keys and its values. To make things worse, the syntax of the language makes it incredibly easy to create and populate dictionaries (unlike, say, in C++). Combine these two facts together and the temptation to abuse a dictionary to implement a structured data type is high.

July 4, 2013 · Tags: <a href="/tags/python">python</a>, <a href="/tags/readability">readability</a>
Continue reading (about 5 minutes)

Readability: Abuse assertions

Assertions are statements to ensure that a particular condition or state holds true at a certain point in the execution of a program. These checks are usually only performed in debug builds, which means that you must ensure that the expressions in the assertions are side-effect free. Because assertions are only validated in debug builds, you can abuse them to make your code more readable without impacting performance and without having to write a comment. Every time you write a line in which you assume a particular machine state that is not clearly implied by the code immediately preceding the new line, write an assertion.

July 1, 2013 · Tags: <a href="/tags/readability">readability</a>
Continue reading (about 3 minutes)

Readability: Avoid comments

One of the best things you can do to improve the readability of your code is to avoid comments. “Uh, what?"—I hear you say—“That goes against all good coding guidelines, which state to heavily comment your code!” Right. Except that the real goal is to have valuable comments only, and doing so is a (very) complex matter. The code should document itself at all times, and be crystal-clear at doing so. Redundant or useless comments hinder readability, if only because their presence denotes that the code is not clear enough to be self-descriptive, because they are obsolete, because they are confusing, or because they very frequently include typos or grammar mistakes.

June 27, 2013 · Tags: <a href="/tags/readability">readability</a>
Continue reading (about 5 minutes)

Readability: Document your types

Wow. The previous post titled Self-interview after leaving the NetBSD board has turned out to be, by far, the most popular article in this blog. The feedback so far has been positive and I owe all of you a follow-up post. However, writing such post will take a while and content must keep flowing. So let’s get back to the readability series for now. In dynamically-typed languages1, variable and function definitions do not state the type of their arguments. This is quite convenient when writing code, but results in very hard to read “stuff” later on. Consider this snippet:

June 24, 2013 · Tags: <a href="/tags/python">python</a>, <a href="/tags/readability">readability</a>
Continue reading (about 3 minutes)

Readability: Mind your typos and grammar

I can’t claim to be an expert writer—not in English, and not even in my native languages—but I do put a lot of attention to whatever I write: emails, presentations, letters and, of course, code. As it turns out, code has prose in it most of the time in the form of comments and documentation. So, when you write any text in your code, engrave this in mind: any obvious typos and/or any grammar mistake very quickly denote sloppiness in what you wrote. If that is the impression the reader gets from your comments… why would he trust that you have been less sloppy when writing the code itself? Let me tell you that they won’t, with good reason.

June 17, 2013 · Tags: <a href="/tags/readability">readability</a>
Continue reading (about 2 minutes)

Readability: No abbreviations

When you are writing code, it is very tempting to shorten the names of functions and variables when the shortening seems blatantly obvious. All of us have, at some point, written calc_usage instead of calculate_usage; res instead of result; stmt instead of statement; ctx instead of context; etc. The thought goes “well, these abbreviations are obvious, and I’ll be a much faster developer!” Wrong. You might think you are faster at typing, but you don’t write code in one go and never ever get back to it again. As we have already mentioned, code is usually only written once and is later read many times, possibly by people other than the original developer. At the very least, I’d expect you going over your code once before checking it into your repository. Spending the extra minute it takes to write words in full will benefit you and your readers.

June 13, 2013 · Tags: <a href="/tags/readability">readability</a>
Continue reading (about 2 minutes)

Readability: Blank lines matter

Vertical spacing is important for readability reasons: group together pieces of code that should not be split apart, and otherwise add blank lines among chunks of code that could be easily reordered and/or repurposed. That’s a pretty loose suggestion though, so let’s look at some specific situations in which you want to consider your vertical spacing practices (both adding and removing). Give some air to long functions Functions longer than a handful lines generally deserve some vertical spacing. A first guideline is to separate the return of the result value (along all of its boilerplate) from everything else that the function may be doing.

June 10, 2013 · Tags: <a href="/tags/readability">readability</a>
Continue reading (about 4 minutes)

Readability: Blocks and variable scoping

In a dynamically-typed language, it is common for the scoping semantics of a variable to be wider than a single code block. For example: in at least Python and the shell, it is the case that a variable defined anywhere within a function —even inside conditionals or loops— is reachable anywhere in the function from there on. To illustrate what this means, consider this snippet in which we define a function to compute the CPU requirements needed in a database system to support a set of tables:

June 6, 2013 · Tags: <a href="/tags/python">python</a>, <a href="/tags/readability">readability</a>
Continue reading (about 4 minutes)

Readability: Series introduction

Dear readers, This post is the beginning of a new series on the idioms and style that I use to keep code readable and obvious. I often get positive comments when undergoing peer reviews at Google and externally, so I am going to share such personal style in the hope that it might be useful to some of you. Explaining these ideas to coworkers when I review their code has proven to be useful in the long term.

June 3, 2013 · Tags: <a href="/tags/readability">readability</a>
Continue reading (about 2 minutes)