When Does Code Formatting Actually Matter?
I have burned a lot of cycles discussing trivialities of code style, and you probably have too. It’s super annoying, wasteful, and doesn’t lead directly to anyone becoming a better programmer or delivering a better product. I’m talking about code review here. Those pedantic comments about white space, capitalization, and syntax are productivity killers. Programmers I’ve worked with (and myself) often smile, giggle, and chalk it up to a form of OCD (a mental disorder).
I’m not suggesting code formatting doesn’t matter. It definitely does. But every team of programmers can benefit from taking a pragmatic approach to maintaining consistent formatting and style in their code. Programmers shouldn’t focus on superficial whitespace for the sake of indulging their OCD, but should focus where it will lead to an improved product.
That’s just like, your opinion
In my opinion, code should be clustered into stanzas, with a single blank line between each stanza. Another member of my team may disagree. Their opinion might be even stronger than mine about precisely where a blank line should go. Matters of pure opinion should not come up in code review. Programmers should ask themselves “is this my opinion, or am I suggesting a meaningful improvement to the code?”
Not all white space is created equal
Blank lines with leading white space are the leading cause of ulcers in programmers. Multiple blank lines are an eyesore. The truth is they really don’t matter, so you shouldn’t comment on them (don’t flip your desk, more on this coming). Some white space, however, is very important. With a basic knowledge of regular expressions, a programmer should be able to quickly search for variable declarations of a particular type, assignment of a particular variable, function calls vs definitions, etc. Inconsistent white space makes this a much more difficult task.
Programmers should spell variable and function names correctly. This is pretty obvious, and typos are always accidental. Spelling is something programmers should absolutely comment on in code review, and again, it comes back to having an easily searchable code base. We’ve all gone on a wild goose chase for a function that we later found had a typo. The time spent upfront, correcting the spelling error, will likely outweigh the time wasted searching for that function, variable, or class.
Optimize for clean diffs
Don’t sneak in white space and indentation changes into your commits, or you’ll screw up the change history. Nobody wants to read another piece of history before getting to the source of a bug. If your team uses tools to help delegate tasks based on history, you’ll just be adding noise to that signal. You’re probably paying for that tool, so get your money’s worth. Trailing commas make adding something to the end of a collection literal a
+1–0 (one colour) change, instead of a
+2–1 (two colour) change. They look weird at first, but they’ve come to help you and your team.
Do your team a favour: get a linter
Add a linter to your project on day 1. If you’re using a relatively mainstream language there’s probably a good one readily available and easy to setup. After that, forget this whole article because it’ll be automatic.
Code that is easy to maintain leads to a better product. Automate maintainability, stop fighting with your team, and live a happier life.