The code formatting problem, and how to solve it
I’d like to show you a short and sweet piece of code, and I want you to take note of whether you have any thoughts or feelings on what the code looks like.
Ready? Here it is:
So, what were your reactions?
Overall, this is perfectly valid Java code — but did it seem properly formatted to you? Did the spacing and indentation seem off, or was it just right? Were you irked by String args[] instead of String[] args? Were you bugged by the { being on its own line?
If any of those things floated through your mind while reading the code, I’m about to say something that might come as a surprise:
You shouldn’t have been thinking about any of those things while reading that code.
…but it’s not your fault if you were.
Before you start booing, throwing tomatoes, or farting in my general direction, please allow me to explain!
If you’re already in the camp that a programming language is “just a tool” to get stuff done, and you don’t care about aesthetics… great! You probably don’t need any convincing. (Also … why did you even click on this article?)
But if you’re like me, you treat code as an expressive art form. You appreciate a beautiful piece of code, and have your own opinions about “beautiful code” versus “crappy code.”
Having said that, I think there are more places we can be artful and creative than in the amount of white space we choose to sprinkle in, and in the amount of indentation we choose to apply.
Here are a few examples:
- Choosing variable names that are concise, yet unambiguous
- Using “guard clauses” to reduce nesting and make the code look “flat”
- Using the elegant “Arrange, Act, Assert (AAA)” pattern in unit tests
Don’t get me wrong: I’m not saying that we shouldn’t care about how our code is formatted.
I’m saying that we shouldn’t have to.
The solution to the code formatting problem is this: every programming language should have one, and only one, valid way to format code.
If there is only one valid way to format a piece of code, then formatting would be a non-issue! None of us would ever have to think about how the code is formatted. Hooray!
We would be able to focus our attention entirely on writing concise, readable, well-tested, efficient code that is error-free and does what it is supposed to.
Consider this piece of code. It’s exactly the same as the one from earlier, except it was run through an unofficial Java formatting tool:
If there were only one, standardized way to format Java code, and this code formatter adhered to that standard, then the program above would pretty much be the only way to write a “hello world” program in Java that compiles and does what it is supposed to.
If you saw this code during a code review, you wouldn’t be thinking things like “ugh, I wish they were using 4 spaces,” or “I wish they would put each curly brace on its own line,” because you would be used to all Java programs being formatted like the one above!
Ideally, it wouldn’t even be possible to compile a program that isn’t properly formatted according to the official language standard.
This would guarantee that you would never see any poorly formatted code in any code that actually works, and you can instead focus on what the code is doing, not how it looks.
Many languages come with standard formatting tools, like gofmt and dartfmt. But even these languages do not treat formatting errors as compile-time errors.
The JavaScript ecosystem is an especially bad offender. The JS standard doesn’t specify whether lines should end with semicolons, whether let or const should be preferred to var, whether multi-line lists should end with trailing commas, whether parentheses are preferred when writing new Foo() … (the list goes on). There are various popular style guides and enforcement tools, like eslint-config-airbnb, but none that are officially required by the standard.
In JavaScript and many other languages, simple formatting decisions are all left up to the programmer. But why should they be? Why can’t there be a standard way of doing things?
For JS, maybe the ECMAScript folks should vote on what should be considered the “official” JS format, and all JS code should start migrating towards that format. In the long run, all JS developers would greatly benefit from spending less time configuring tools like ESLint and Prettier and instead getting straight to work on their projects.
Of course, some exceptions would need to be made. JavaScript, for example, often gets compressed and minified, meaning that whitespace is stripped. The browser shouldn’t refuse to execute minified JS. But maybe the browser could require those files to end with .min.js.
Languages like TypeScript, which get compiled to JS, are still in a stage of development where they could introduce these kinds of standards without causing any problems. Languages like C++ could do the same, since they could just introduce the standard format in future major versions of the language.
I hope you agree that in an ideal world, all programming languages would have one — and only one — way to format a given piece of code.
Thanks for reading, and I’d love to hear what you think!
