Code Review Best Practices - Formatting Standards

Many development teams spend an inordinate amount of time arguing over styling and formatting preferences, such as:

• Whether to use single quotes or double quotes
• Whether curly braces go on the same line or the next line
• How to wrap long lines of code

Although these preferences are somewhat subjective, there's something to be said for consistency. Imagine you're reading a book where one page is double spaced and the next is single spaced. On one page, important terms are bolded, and on another page, important terms are underlined. As a reader, those types of inconsistencies can get between you and the content of the book. Likewise, in code, these types of styling and formatting preferences do make a difference.

Since styling comes up frequently during code reviews, it's a good idea to have a strategy in place for dealing with it. Here are three levels of maturity for dealing with code formatting on a development team.

Level 1 - No Styling Standards

Most teams that do not have standards for styling are small enough that it hasn't become an issue yet, or the developers on the team all tend to format the code similarly to begin with.

Once you've got more than a few developers, though, you'll probably start noticing some dissonance in code styling and formatting. And that’s when it's important to move on to level 2.

Level 2 - Documented Styling Standards

Once teams become large enough, or have enough turnover in their members, it makes sense to document your standards up front. When the formatting standards are documented, it gives you an authority to point to during code reviews. Instead of arguing about who likes what during the review, you decide those things ahead of time.

As long as you adhere to those established standards, you almost eliminate the possibility that they'll arise during reviews. Of course, you might still discover during a code review that your standards did not address some particular formatting case. No sweat - just decide how you want to handle that case, and then add it to the standards document!

Level 3 - Auto-Formatting

I expect that most teams fall under level one or two. But an even better solution is to utilize the Auto-Formatting features in your IDE. Rather than depending on your developers to format code according to spec, you let the IDE do it.

This gives you a productivity boost in that it allows the developer to concentrate on the content of the code rather than on its presentation -- a distinction that we readily apply to HTML/CSS but fail to make within our own coding practices! When I'm writing code, I don't want to concern myself with how it's formatted. I want to concern myself with stuff like whether I'm following good design practices.

Now, I'll admit I've had hit-or-miss experience with these auto-formatters so far. Often, the options in such tools are limited, and don't allow you to account for every case that your formatting standards document dictates.

Still, even if you can only account for 80% of the formatting spec in your auto-formatter rules, do it! That's 80% less thinking about formatting that your team will have to do.