Design for Readability

I feel strongly about writing good code; for me, it is an art that is honed over time. It needs to be written well, structured nicely, and easy to understand; one aspect that often goes neglected though, is the readability of the code itself. Intelligent formatting is such an underrated aspect of code; there are benefits in so many areas. It makes it very easy for a peer to review your code, for one. Quoting from David Bryant Copeland’s blog,

But, it’s not just the content — the code itself — that affects readability. How it’s presented matters and if we’re going to talk about presentation, we have to talk about typography.

Today, there is a lot of work going on around automating this area; there are tools to ensure consistent formatting to some degree. Intellij-Idea has an auto-format feature for Java code that does most things right and saves time too. Checkstyle for Java is a god-send too; catches most inconsistencies early. I am a huge fan of Prettier too; while I rarely write JavaScript code nowadays, I incorporate a lot of ideas from there in what I write. While automated styling does work at most times, one can always do better. The following quote from Practical Typography applies very well here:

Good ty­pog­ra­phy is mea­sured by how well it re­in­forces the mean­ing of the text, not by some ab­stract scale of merit. Ty­po­graphic choices that work for one text won’t nec­es­sar­ily work for an­other. (Corol­lary: good ty­pog­ra­phers don’t rely on rote so­lu­tions. One size never fits all.)

My workflow when writing something new normally involves one step of automatic formatting followed by tweaks to enhance readability before I raise a code review request. I havetried to crystallize some of the techniques I use; I’ll list them below:

**All code is lifted from random open-source repositories

Function Definitions:

Consider the following snippet:

While it is readable, it could be made a lot better:

Here is what I did:

1. Lexicographical sorting by class-name to make things easier to find
2. The first line was excessively long; long lines make it harder to focus the code at hand; this is solved very easily by simply starting the arguments in the next line
3. Vertical lines: by ensuring that the argument names are all aligned in a single line, we give them the look of a table, which one is more comfortable with consuming, especially in print media. I have given out two variants: one with the class names right-aligned and the other with left-align; I prefer the right alignment, but I feel both approaches serve the purpose well.
4. Finding matching brackets can be one of the most annoying things one goes through while reading code. A simple rule of thumb that I have found to work for me is to have the same indentation for the closing brace as the line containing the opening brace.

Classes, inheritance and interfaces:

How many times have we seen a code snippet that looks like the following:

Formatting it as below makes it a lot more readable:

Again, notice the table-like alignment similar to #3 from the previous section.

Function invocations:

I feel there is no need to reinvent the wheel here; Prettier does a solid job in this regard; I’ll highly recommend reading the paper by Wadler too.

Lifting the example straight from Prettier,

foo(arg1, arg2, arg3); // Concise enough; no need to change

// Can do better
foo(reallyLongArg(), omgSoManyParameters(), IShouldRefactorThis(), isThereSeriouslyAnotherOne());

// Much cleaner!
foo(
  reallyLongArg(),
  omgSoManyParameters(),
  IShouldRefactorThis(),
  isThereSeriouslyAnotherOne()
);

Comment blocks

Code comments are always a great way to enhance the readability of code; they help augment the reader’s understanding of the code with the relevant context. I do not have too many strict rules about comment blocks; there are a few that I do stick to though:

1. Keeping the maximum line-width of comments to 80 characters (or even fewer). This results in nice blocky comments that the reader can consume easily. This fits in very well with Butterick’s Practical Typography rules : “The av­er­age line length should be 45–90 char­ac­ters (in­clud­ing spaces)”
2. Use comment tags where necessary; I like to use TODO , TECHDEBT https://en.wikipedia.org/wiki/Comment_%28computer_programming%29#Tags

I’ll end my post here; do drop a comment with patterns that you use that help in this regard!