Design for Readability
Tags: programming, prettier, typography
Published: 2017-12-10 19:39:36

---
title: "Design for Readability"
published: true
tags: programming,prettier,typography
canonical_url: https://medium.com/@ameyakarve/design-for-readability-f4f1544528ee
---

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_](http://naildrivin5.com/blog/2013/05/17/source-code-typography.html),

> 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](https://prettier.io/) 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&nbsp;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&nbsp;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&nbsp;below:

_\*\*All code is lifted from random open-source repositories_

**Function Definitions:**

Consider the following snippet:

{% gist https://gist.github.com/anonymous/0841ed200cef67b63838c3563c229482 %}

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

{% gist https://gist.github.com/anonymous/a302165cb93c4e1907573f6087c74089 %}

Here is what I&nbsp;did:

1. Lexicographical sorting by class-name to make things easier to&nbsp;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&nbsp;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&nbsp;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&nbsp;brace.

**Classes, inheritance and interfaces:**

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

{% gist https://gist.github.com/anonymous/c6ef746cf53fe6b1e230ef80785470a1 %}

Formatting it as below makes it a lot more readable:

{% gist https://gist.github.com/anonymous/2bb8470fb0d68c644d35328ef8c79c8b %}

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

**Function invocations:**

I feel there is no need to reinvent the wheel here; [Prettier](http://jlongster.com/A-Prettier-Formatter) does a solid job in this regard; I’ll highly recommend reading the paper by [Wadler](http://homepages.inf.ed.ac.uk/wadler/papers/prettier/prettier.pdf)&nbsp;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&nbsp;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&nbsp;](https://practicaltypography.com/summary-of-key-rules.html): “_The av­er­age_ [_line length_](https://practicaltypography.com/line-length.html) _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](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&nbsp;regard!