Software Teams Should Use a Code Style Guide

I used to have strong opinions about code style and syntax. I mean, has anyone seen the Silicon Valley episode about tabs vs spaces?¹ I thought I had to care about stuff like that to be a good developer 😂. I even created my own eslint plugin. Now, I couldn’t care less about any particular style rule - for example spacing of if statements, or single vs double quotes.

What I do care about is consistent code style so I don’t even have to think about this, and I can copy and paste code in my editor and have it be auto-formatted on save. If only there was a tool that could standardize this for you..

Prettier

Prettier is an opinionated code formatter that handles all of this for you. It includes sensible defaults out of the box, with limited configuration options (this is actually on purpose so you don’t need to drown in a config file like with eslint). Their “Why Prettier” has pretty compelling reasons but I wanted to describe a few reasons from my experience.

“Let Computers Do The Boring Parts”

Michael Lynch has a fantastic blog post where he talks about how automating as much as possible for code-reviews on teams makes everyone more efficient (and happy). Code syntax is a perfect example of this. Life is too short for nitpick PR comments about spacing of brackets. It adds unnecessary noise and distracts everyone from the actual important functionality a PR has. This is commonly referred to as “bikeshedding”.

Not everyone may agree with a given style guide - there are multiple choices after all (prettier standard, etc). But developers should realize that code is managed by a team and not a single person. A developer who writes some “beautiful” custom-formatted code might leave in 6 months. The next dev who looks at it thinks it’s confusing and ugly. The point is - we may all have different opinions about syntax, but style guides provide a reasonable default.

Why Use a Style Guide at All?

Some devs may argue “why should we even care about silly things like quotes”. Why can’t each developer just choose whatever they want? I’ve been at companies that adopted this approach and it’s certainly not terrible. But it prevents devs from enabling format-on-save in their editor - or else a one line change to a file could end up in a massive diff, something like this:

Removing the need to have discussion about code formatting makes teams more productive and more focused. Consistently-formatted code also has a few more advantages:

• Easier to search the whole codebase for something (what if you search for a string "foo" only to realize it was single-quoted in some place instead?) Make it easier on yourself..
• Easier to navigate different files and understand / see patterns in code.

How to Adopt

Okay, so maybe you’re convinced about the benefits of a style guide, but you work for a company that already has a huge codebase. How on Earth are you going to format all of the code?

I spearheaded this at Logikcull a few years ago. We discussed it among the team and decided to tackle it all at once. My suggestions:

• Dive into it and just reformat the entire codebase at once. Since prettier only deals with stylistic things, it shouldn’t introduce any bugs².
• The diff will be impossible to actually review for a large codebase. This is what it looked like at logikcull:

• Add the commit sha containing the autoformat changes to a .git-blame-ignore-revs file and setup your git config to reference it with

[blame]
  ignoreRevsFile = .git-blame-ignore-revs

Without this, the git history of files would be greatly complicated - almost every file would show the last edited date as the time of the autoformat commit.

• Setup a pre-commit hook to auto format any staged files with prettier to keep code being auto-formatted. At logikcull, we used the open source tools Husky and lint-staged for this. Spread the word to devs about the ease of autoformat on save directly in the editor - this makes copying and pasting code much easier and improves productivity.

We set this up at logikcull for typescript/javascript in spring of 2020 and it’s been smooth ever since then. In 2023 we adopted a similar style guide for the ruby codebase due to the same problems described in this blog post.