Format Your Code

Do you like coding without syntax highlighting?

As far as I can tell, the biggest benefit of syntax highlighting is widening the bandwidth of the screen-to-brain channel, by using colour to quickly communicate information that would otherwise take brain power to deduce. It also adds layering to the characters on screen, letting you focus on the important parts, while keeping the unimportant around but subdued, not screaming for attention.

Anybody who has done a large code review in a web interface without highlighting knows how brain-draining it can be to read code that way. In fact fetching the branch and reading the code in your editor instead of the web browser can be a great way to save brain cycles[1].

White space in code can be used to similar ends as syntax highlighting.

[NEED EXAMPLE]

There are some who argue that unless their editor does it automatically for them, they won’t bother with formatting code. It’s dumb manual work that’s beneath them. I find that this stance misses the point. Most people don’t enjoy writing unit tests, it’s repetitive, boring manual work, but that’s a poor reason to not write them[2]. More importantly, formatting code is about communication, about bringing to the surface information that is there but not visible, to a human. Yes, a subset of it may be easy to automate, but at the end of the day, it’s about humans making code more readable for other humans — at least a subset of this is guaranteed to be ad hoc, use case specific. Besides, automation allows you to not think about the problem of readability of your code, which at this stage is the opposite of what we want — we want to be fully conscious of coding for readability, until it becomes second nature. In a sense, you’ll achieve the same result, automation (through muscle memory), but in this case it will stem from the correct foundation and reason. So please give up on the reformat-on-save automation. It’s really not that much effort, certainly far less than good quality naming.

Prose is composed of words which are grouped together into sentences, which are then grouped into paragraphs, which in turn are grouped into sections, chapters, parts, and volumes. Code can, and should be organized in a similar fashion, and the formatting of all these units should be consistent, to communicate intent and reduce cognitive overheard of reading the code.

A type/interface definition that consists of multiple lines? That’s a paragraph, so have one empty line between it and the next paragraph.

A few chained calls to process some data? That’s a paragraph, so have one empty line between it and the next paragraph, i.e. the code that’s probably using the prepared data.

A top level constant? That’s a paragraph, even though it consists of a single line.

A few top level constants that are semantically related? That’s a paragraph too.

What you do beyond paragraphs depends on the language you’re coding in, and your project structure. For example, in typed languages, the following structure may be typical:

import { UUID } from "lib-lang"

import { this, that } from "whatever"
import { theOther } from "somewhereElse"


type AwesomeThing {
    id:                   AwesomeThingId
    reasonForAwesomeness: string
}

type AwesomeThingId = UUID


class AwesomeThingService {
    ....
}

There are three sections here — the imports, the type definitions, and a class. So the sections are separated by two new lines, while paragraphs within sections are separated by one. Note how the imports are organized — the language level imports are a paragraph on their own, and less global level imports are in a separate paragraph.

[1] We use BitBucket, and as of now it doesn’t have built-in syntax highlighting, and “I’ll tweak your DOM” type Chrome extensions are admirable but perform poorly. [Since the time of the original writing, online pull request tooling has improved significantly]

[2] The right reasons for not writing unit tests are discussed here.

Next: Everything Should Have a Home ⇒