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.
Good typography is measured by how well it reinforces the meaning of the text, not by some abstract scale of merit. Typographic choices that work for one text won’t necessarily work for another. (Corollary: good typographers don’t rely on rote solutions. 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
Consider the following snippet:
While it is readable, it could be made a lot better:
Here is what I did:
- Lexicographical sorting by class-name to make things easier to find
- 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
- 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.
- 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.
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!
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:
- 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 average line length should be 45–90 characters (including spaces)”
- 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!