On formatting standards

by Jeff Langr

May 05, 2022

On formatting standards

Few topics in software development are more contentious than formatting standards. Tabs vs. spaces, indentation standards, and brace alignment standards (thank you Python for finding a way to eliminate some of these arguments) are often hotly contested, and it doesn’t end there. You can find yourself in the midst of dozens of arguments around code layout minutiae.

Then there’s the bigger argument of having standards at all. Do we really need a standard for something as trivial as formatting? Are coding standards oppression? Is it overreach to enforce formatting standards (or other coding standards) by gating source integration via a linter?

The cost of inconsistency

I recently worked in a team where they not only adopted a rather large linter configuration for their JavaScript code, but added numerous additional constraints. I found some of these to be fairly annoying, particularly since automatic formatting didn’t correct them. I felt a bit stifled and slowed-down in this environment.

Still, I attach a high value to consistent-looking code. In fact, the code I produce without the use of much automatic formatting ends up highly consistent, because I’ve developed a habit of crafting the code that way. It’s a bit obsessive, but I always find code formatted “my” way to be far faster to read. If I have to read bad code that’s also formatted particularly poorly, I will actually reformat it before I bother trying to read it.

I believe inconsistently-formatted code creates a cognitive friction (not quite what A. Cooper talked about), particularly when it involves either vertical or line-wise spacing. Lots of friction wears us down over time. A consistent standard allows you to focus on the content more by removing distractions. Try reading a book or web page that doesn’t follow established layout and formatting standards. (And if you don’t believe me, I can guarantee I’m able to format your code in a way that makes you weary. See above image for a small taste.)

Multiple formatting styles in a codebase is a pretty messy world. Chaotic application of styles can waste time through increased clutter when trying to understand source diffs (though “ignore whitespace” can help).

We should care

Folks like Tim Ottinger and myself have coached many dozens of teams over the years. We’ve seen countless codebases, along with a wildly varying set of standards. As a result, while we have our own preferred standards, we’ve generally learned to live with whatever standard the team currently follows. (I can’t recall a standard so egregiously bad that I couldn’t work in the codebase.)

As someone whose job often includes helping the whole team improve, I absolutely care that my teammates don’t end up frustrated with the codebase. Even if I dislike their chosen standard, it doesn’t take me long before I’ve accepted it and habitually code that way. I suspect most people are similarly capable of adapting to a new standard, even if they’ve made arguments for another standard for their whole career. And I also think most folks appreciate the consistency.

Ultimately, I care about consistent formatting enough to do it where I can, and not as much the specifics of the individual standards.

So what? Well, you too might be able to help your team establish a consistent standard that helps the people on your team who really do care, even if you don’t.

Tips for creating a standard

Here are recommendations on building a standard with your team, whether it’s a formatting standard or something less trivial:

  • Start with an empty list. While you can get ideas from an existing voluminous standard, you’re best off growing from nothing into a small list that the team can follow.

  • Solicit a list of items that team members really care about. Ignore everything else (you can always add items later). For formatting standards, prefer items that an automated formatter can handle. (News flash: There are always exceptional cases. If you can’t find a way to override automatic formatting, perhaps omit the standard.)

  • Discuss each item with the intent of quickly coming to consensus. Timebox discussions on items for which you can’t reach consensus. Set these aside.

    • Ask everyone to honestly answer, “Could I learn to drop my pet standard and live with another?”

    • And also: “Would it kill us if there was no standard here?”

    • But tap your empathy before dismissing items that might genuinely cause others pain. Remember that for some people, legitimate cognition challenges can severely impact their ability to work with code. You must ensure your standard works for them.

  • In case you don’t think I meant it, I repeat: Ignore anything that doesn’t have real relevancy. If smoeone’s sales attempt on a potential standard doesn’t sway anyone else, drop it.

  • Seek a better design, one that promotes smaller functions/methods. Formatting matters a lot less when functions are 1 to 3 lines long on average.

  • For formatting standards, configure what you can in an automatted formatter and ensure it always gets executed every time when code is about to be integrated. Make sure you can apply the same formatting configuration in the IDE as well.

  • If you still have one or more formatting items for which you can’t reach consensus: See if it’s possible to configure an alternate automated formatter that aligns with the interests of dissenting developers. They can use the alternate automated formatter personally and then let the team-blessed formatter do its work once they’re done.

  • Revisit the standard as often as needed—when someone is frustrated with it, wants to suggest an addition, or when it’s obvious that people are violating it.

Ottinger reminds us that “some people see a coding standard as a team agreement, and those who don’t follow it as uncaring. Others see a standard as one person oppressively imposing their subjective, personal preferences on others. Formatting standards are trivial, but invite ongoing resentments due to their symbology.”

Damned if you do, damned if you don’t? Following the above steps to establish standards will at least get you somewhere: It’s not one person’s mandate, and you built it up from scratch to the last possible point of consensus… for now, at least.

All that said, tabs are just wrong. Sorry, Richard (and Silicon Valley writers who think people repeatedly hit the space bar to indent, and who forget that consecutive spaces compress pretty well).

Share your comment

Jeff Langr

About the Author

Jeff Langr has been building software for 40 years and writing about it heavily for 20. You can find out more about Jeff, learn from the many helpful articles and books he's written, or read one of his 1000+ combined blog (including Agile in a Flash) and public posts.