Readability - Julio Merino (jmmv.dev)

5 ways to instantiate Rust structs in tests

I’m a big fan of static typing and I’ve found that using narrow types for each entity in the object model of my programs reduces errors. Rust is particularly well-suited at this task: its lack of implicit type conversions eliminates surprises, and its ownership semantics allow type transformations with zero cost. Unfortunately, (ab)using narrow types in an app’s domain is really annoying when writing tests. While non-test code rarely instantiates new objects—in the case of a REST service, this would only happen at the service’s boundaries—tests instantiate objects infinitely more times than non-test code. Code patterns that may seem reasonable in non-test code can become unbearable in tests. In this post, I want to look into the various ways in which you can instantiate strongly-typed objects. For each, I show examples and describe their pros and cons. And yes, as a matter of fact, I have tried them all before… and I can’t yet make my mind as to which one is best.

October 6, 2023 · Tags: <a href="/tags/programming">programming</a>, <a href="/tags/readability">readability</a>, <a href="/tags/rust">rust</a>
Continue reading (about 10 minutes)

Tips on formatting Markdown lists

Lists are a very common construct in technical documents, which is the kind of material I most often write and review. But getting complex lists to look right is tricky, especially when authoring them in Markdown. Let’s look at a couple of tips to ensure that any list you write will always be correctly formatted with ease.

July 7, 2022 · Tags: <a href="/tags/markdown">markdown</a>, <a href="/tags/readability">readability</a>
Continue reading (about 7 minutes)

Constructors and evil initializers in C++

One of the three key tenets of Object Oriented Programming (OOP) is encapsulation: objects contain a state that, when observed from the outside, is always internally-consistent. Unfortunately, C++ codebases where exceptions are forbidden often violate this rule when they separate object initialization from construction. Let’s see why that’s a problem and how to address it.

November 24, 2021 · Tags: <a href="/tags/c++">c++</a>, <a href="/tags/readability">readability</a>
Continue reading (about 8 minutes)

Definitions and initializations in C++

When reviewing an incoming C++ PR last week, I left a comment along the lines: “merge local variable declaration with its initialization”. But why? Is this just a stylistic issue or is there something deeper to warrant making the change? Let’s look at stack frames, C, and then C++ to answer these questions.

July 12, 2021 · Tags: <a href="/tags/c">c</a>, <a href="/tags/c++">c++</a>, <a href="/tags/readability">readability</a>
Continue reading (about 11 minutes)

Encode your assumptions

The point of this post is simple and I’ll spoil it from the get go: every time you make an assumption in a piece of code, make such assumption explicit in the form of an assertion or error check. If you cannot do that (are you sure?), then write a detailed comment. In fact, I’m exceedingly convinced that the amount of assertion-like checks in a piece of code is a good indicator of the programmer’s expertise.

February 7, 2019 · Tags: <a href="/tags/bazel">bazel</a>, <a href="/tags/production-software">production-software</a>, <a href="/tags/readability">readability</a>, <a href="/tags/software">software</a>
Continue reading (about 4 minutes)

Shell readability: local

As most programming languages with support for functions, the shell offers locally-scoped variables. Unfortunately, local variables are not the default. You must explicitly declare variables as local and you should be very strict about doing this to prevent subtle but hard-to-diagnose bugs. That’s it! What else is there to say about this trivial keyword? As it turns out, more than you might think.

March 13, 2018 · Tags: <a href="/tags/readability">readability</a>, <a href="/tags/shell">shell</a>
Continue reading (about 5 minutes)

Shell readability: strict mode

Some programming languages have a feature known as strict mode: a setting that makes the language interpreter disallow certain obviously-broken code that would otherwise work. The simplest examples are JavaScript and Perl but, as it turns out, the shell also has something akin to this feature. The “strict mode” name, however, is unofficial, so you won’t find many references to it online. You can enable the shell’s strict mode by doing one of the following:

March 9, 2018 · Tags: <a href="/tags/featured">featured</a>, <a href="/tags/readability">readability</a>, <a href="/tags/shell">shell</a>
Continue reading (about 6 minutes)

Shell readability: function parameters

The shell supports defining functions, which, as we learned in the previous post, you should embrace and use. Unfortunately, they are fairly primitive and their use can, paradoxically, introduce other readability problems. One specific problem is that function parameters are numbered, not named, so the risk of cryptic code is high. Let’s see why this is a problem.

March 2, 2018 · Tags: <a href="/tags/readability">readability</a>, <a href="/tags/shell">shell</a>, <a href="/tags/shtk">shtk</a>
Continue reading (about 3 minutes)

Shell readability: main

Our team develops Bazel, a Java-based tool. We do have, however, a significant amount of shell scripting. The percentage is small at only 3.6% of our codebase… but given the size of our project, that’s about 130,000 lines—a lot, really. Pretty much nobody likes writing these integration tests in shell. Leaving aside that our infrastructure is clunky, the real problem is that the team at large is not familiar with writing shell per se. Few people are these days actually.

February 26, 2018 · Tags: <a href="/tags/readability">readability</a>, <a href="/tags/shell">shell</a>, <a href="/tags/shtk">shtk</a>
Continue reading (about 2 minutes)

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)

Posts: Readability