Dream formatter

I have my own preferences about formatting code. Some developers do but I’ve met others who don’t care and just want to get on with the code. On a team you’re dealing with other developers who will have their own ideas about this. How does that work? Do you each do your own thing? Do we all have to do the same thing? Can we even manage to do the same thing?

A formatting tool is one way to ensure that one way of formatting code is followed. However, I mentioned recently deciding to avoid these because of their lack of flexibility. Lets think about the sort of tools out there and what I really want.

One true format

One way a formatter can work is by giving you no choices at all. My experience with this was through black, a Python code formatter. I can see for those who don’t care and just want to get on with the code this is great. If everyone uses the same formatting then the details of the formatting will sink into the background. After a while you can read the code better than before as their are no surprises.

However, the rules can seem wrong. Say, the maximum line length of 79 characters. To me this seems archaic, a left over of small screens and dot matrix printers. All code use to written without indenting, back in the time of goto. Nowadays we indent for control flow, functions, classes and namespace. So much space can be used up before we write anything.

More significantly it doesn’t fit with my view that there isn’t a single right way of doing things. Reading the actual style guide for Python reveals a little bit more flexibility. However, a single minded tool doesn’t account for this. I can see why people might choose these but it’s not for me.

Option based

Another way is for the formatter to have options which you can pick from. My experience with this was through clang-format, a C++ (plus others) code formatter. This might include such things as: tabs or space, where to put your braces, where to put your spaces, or the maximum line length. There are a bunch of existing formats out there, e.g. Google, Mozilla or Microsoft, which you can just copy or you can go through each one of the options individually. However you set the rules that’s how your code will be.

For me this is better but the problem is that it decides exactly how your code will be. Lets say all you care about is that everything is done with space not tabs. That way everyone gets to see the same thing however their environment is set up. That’s not possible because the code is completely reformatted each time you run the formatter. It means introducing the formatter is all or nothing. I think this makes it harder to choose the options because you have to do everything at once. If you have any disagreements in your team then someone is going to be unhappy. It’s going to completely change the codebase. A single commit which affects everything.

The dream

What I want is something where you can choose to apply or not apply options. If you choose to change tabs to space and nothing else then that is what you’ll get. To me this has a number of advantages:

• Rules can be introduced gradually. A single commit might be used to unify where to put the braces but leave everything else. Looking back through the commit history this shouldn’t be too disruptive.
• Rules can be decided gradually. Maybe the team doesn’t agree or maybe they just don’t know. You can set a few rules to start with, update the code and see if that changes any opinions.
• Rules can be skipped. I think even a good formatter can have trouble wrapping a line of code well. It can certainly do it but making it nice to read or keeping related data together is better done by hand.

Then there are the options themselves. I’ve written code formatting guidelines myself and they set out some broad rules plus a few exceptions. Rather than having a long list of very specific options it would be nice if the options could be, say, hierarchical.

Unfortunately I think a completely reformatter is easier to create. The code can be parsed into an internal representation and then printed back out according to the rules. A partial reformatter has to care about the original representation as well. Still, how hard can it be? (For all I know, much harder.)

In the end

I think code formatting does matter. An awful lot of my job involves looking at code. If a project can have a consistent formatting that’s going to help however it’s achieved. It’s easier to understand code that’s in a familiar style.