Formatting Code (Properly == Consistently)

The first rule of formatting is that code should be consistent. That means that the code should be consistent within itself — that is, within its files — and across the code base.

And consistent with the language itself, or more accurately, the framework and libraries of the language.

Programmers should not try to make a statement with the format of their code. I’ve seen hideous, oddly-formatted code where it seems that the programmers wanted simply to look different, since their alternative style made no improvement in the legibility of the code. Sure, it’s different. But the problem is: it’s different. There is cognitive friction in that I’m reading code that doesn’t look like the other code in that language. It doesn’t look (exactly) like a JDK class. Or a Ruby library. Or part of the C++ STL. It’s different.

One of my primary tenets of programming (and a lot of other things) is: change only one variable at a time.

Nonstandard formatting violates that principle because it doesn’t take the predominant formatting style of a language as a constant, and instead treats it is a variable. So as a reader of that code I must grapple with two variables: the code itself, which is new (thus a variable) to me, and its nonstandard format, also new/different to me, not matching my expectations of how code in the language is supposed to look.

Yes, I know I can just reformat the code. And we can read files with a chain of input stream objects instead of, oh, something like IO.readlines. In the words of Alfred North Whitehead: “Civilization advances by extending the number of important operations which we can perform without thinking about them.”

Said inversely, this means that our experience worsens with the number of variables we have to think about, with which I’m sure any programmer would agree. And that includes code formatting.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s