Peter Krieg's blog

Software Teams Should Use a Code Style Guide

Last updated on

I used to have strong opinions about code style and syntax. I mean, has anyone seen the Silicon Valley episode about tabs vs spaces?1 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:

Github diff showing bunch of meaningless formatting changes

Forcing developers to review meaningless format changes like this is a waste of time. Michael Lynch also has an excellent blog post about 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:

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:

[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.

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.

Footnotes

  1. All jokes aside, you should probably default to tabs on a new project for accessibility reasons

  2. For around 40,000 lines of code changed total, we actually did have one bug from the prettier autoformatting - which was actually an edge-case bug of prettier. This was mostly a quirk with some CSS-in-JS logic we had.. it was an unfortunate bug nonetheless. Rely on your test coverage with the massive autoformat PR, or do some manual testing to feel better about it. Don’t ship it on a Friday!