Automate Your Software Standards

When I was working with the BBC, the age-old debate had arisen again: should we use “cuddled elses” or not? For those not familiar with the debate, it’s asking if we should do this:

if (someCondition) {
    System.out.println("We all gonna die");
} else {
    System.out.println("We not gonna die");
}

Or this:

if (someCondition) {
    System.out.println("We all gonna die");
}
else {
    System.out.println("We not gonna die");
}

For those of you who are not software developers, the differences might seem pedantic. For those of you who are software developers, the difference is pedantic. Unfortunately, it caused a furious debate (as it often does) at the BBC and, as often happens with these debates, work isn’t done. Sometimes tempers flare. And quite often a decision isn’t made.

And that’s actually bad because one developer might “cuddle” that else and another developer working on this code might “uncuddle” it. And they’re not being malicious or petty: “correctly” formatting code is simply something an experienced developer does as part of their job. And that means more commits to your version control system and more work digging through those commits if you’re trying to figure out why something was written in a particular way.

Or worse, you have a developer who decides to write code to format the entire codebase in their personal style and running git annotate $filename shows that developer on all the lines. So you contact this “expert” about the $filename and they say they’ve never heard of it. I’ve run across this mess more than once.

Getting back to the BBC ...

We had agreed we’d use Perl::Tidy to automatically format our code, but at that point, we hit another obstacle because everyone argued about the brace style (if you don’t know what that means, trust me, you don’t care) and no matter how hard we tried, Perl::Tidy couldn’t get the curly braces formatted the way we wanted them to be formatted.

My argument was “who cares? We’ll get used to the new styles. Let’s get back to work.” But another developer, passionate about his brace placement, argued that he could write a PPI hook to fix this. Sigh.

I quietly bet another developer £5 that this approach would not work. I’m sad to say I won that bet. Worse, when the “solution” was ready, it kept hitting edge cases in our code and breaking.

And if you really want to see what a ridiculous timesink this can be, you can choose many different indentation styles such as K&R (and its many variants), Allman, Pico, Ratliff, GNU, ad nauseum

What a waste of time!

The icing on the cake? Though we know having regular formatting of code to show the logical structure of the program makes it easier to follow the code (proof: read minimized Javascript versus unminimized), there’s no strong evidence (that I’ve ever found) a particular type of formatting is better than another. If you disagree, please provide non-anecdotal evidence.

In fact, in the excellent book Code Complete: A Practical Handbook of Software Construction, Second Edition , by Steve McConnell, he dives into this at the beginning of chapter 31. After some discussion of the topic, including referencing some studies on said topic, he concludes (emphasis mine):

Expert programmers often cling to their own styles tenaciously, even when they’re vastly different from other styles used by other expert programmers. The bottom line is that the details of a specific method of structuring a program are much less important than the fact that the program is structured consistently.

Unsurprisingly, these arguments about brace style, cuddled elses, tabs versus spaces, and so on, are almost meaningless. To be fair, there is marginal value to be had in suggesting things such as “shorter variable names for smaller scopes” and “indent to show logical structure”, but being too pedantic about it pisses people off for no good reason.

So how do we fix this?

First, pick a reasonable style you can automate, swallow your pride about the details, and choose your automation tools. Second, consider that—unless you’re pair programming—noone really cares much about the font you’re using, do they? Not really. You’ve set your editor to choose your own font and that’s not written back to your source code, so set your editor to choose your own style and make sure it’s not written back to the source code.

So let’s say you prefer spaces to tabs, with a four-space indent, and you use vim to edit your code. When you open a file, or create a new one, using the BufRead,BufNewFile commands is the first thing you need, or you can create a mapping to apply your style. For example, in your filetype mappings you can add the following:

noremap <silent> <leader>style :call s:ApplyMyStyle()<cr>

function! s:ApplyMyStyle()
    " set up my editor to do the right thing
    setfiletype perl
    set expandtab
    set textwidth=78
    set tabstop=4
    set shiftwidth=4
    set expandtab
    retab " apply my tab/space choices
    " reformat the file
    execute(":%!perltidy -q --profile=myperltidyrc")
endfunction

Now, assuming your leader is the backslash, you can type \style to apply your coding style and never, ever have to pay attention to the silly choices other developers make.

Do I recommend this technique? Absolutely not. You’re going to commit in your own style one day. However, there are git hooks you can write to apply styles when you commit . It’s much safer. A better choice, still, is to just be an adult and admit your “one true style” is a personal preference, not a mandate handed down from heaven. Learn to use the house style in preference to your own and avoid all of the petty arguments in the first place. You won’t look like a better person for it, but you’ll look like a worse one if you tell the other programmers they’re fools for choosing a style different from your own.