Code Quality and Formatters

We should respect process. Is exists to provide accountability and known pipelines for the movement of features from your development box to production sites.

But.

Code quality and standards are often difficult to make a business case for. Why should we carve out time to improve years of unprofessional, difficult-to-read code when there will be no actual improvement to what we deliver to customers?

In addition, lot of developers have very strong opinions about what counts as “readable” code. Have mercy on you if you have to decide between tabs or spaces when two developers have strongly-held opinions on one or the other; or whether four spaces or two is appropriate.

Both of these factors will get in the way of introducing code quality standards to your codebase.

So how do you get over this initial hurdle?

One way is to just do it. Talk to your fellow developers (at least, those who share your belief in craftsmanship for their code), stack hands and get some buy-in, and just start committing code that has gone through automatic formatters.

Get as many folks to add Prettier to their IDEs as you can, automatically formatting any JS files you modify. Have your backend developers install PHP-CS-Fixer as you can so your code adheres to PSR-2 standards. Don’t let people commit code that hasn’t been run through gofmt or elm-format.

Start doing it, and start enforcing it.

By doing this, you can skip the business-case line by asking for time to do this at the expense of your code increasing in quality slowly, but surely. You also might have to fight a bit of extra git spam (which is typically easy to hide via GitHub’s “Hide White Space” feature in pull requests, anyway).

As for choosing standards and tools, my advice is to have not have an eye for the trivial. If your IDE is setup to automatically format on save, and you can avoid wasting your time thinking about spaces versus tabs; semi-colons or no-semicolons; indent levels; etc. Then who cares? Let the formatter fix that junk for you so you can focus on writing testable, clear, quality code.

The only rule of thumb is: the cost of a custom configuration is almost certainly higher than the cost of not configuring your code formatter. Two developers having different Prettier settings and saving over the same file can create some gnarly merge conflicts. Why take the risk? Just use the defaults.

Code quality matters. It helps onboard new people, reduces the cost of context switching, and shows that you care. Just do it. If somebody comes knocking on your door for improving your code quality, push back. Take ownership and pride over what you produce so that it’s not only done, but done well.

Code Formatters

JavaScript (including Node, Typescript, Flow, JSON, JSX, and more), HTML, and CSS: I work mainly in JavaScript and CSS these days. So my go-to, and one I’ve forced my entire team to use, is Prettier, using the defaults. I use this across all files that it works on.

When I work in PHP, I rely on the tools provided by the FriendsOfPHP and Symfony teams to format our code to my team’s preferred (and most PHP codebase’s preferred) PSR-2 standards. To automatically correct errors, we use PHP-CS-Fixer.

But there is an entire world of code formatting out there. If you need to find tools for your language, some kind folks have assembled a huge list at the repo awesome-code-formatters.

Bottom Line

• Use automatic code formatting tools
• Stick to the defaults
• Start doing it today
• Not tomorrow. Don’t sprint it. Do it now.