Word Aligned

Retro-fitting coding standards

2007-01-11 • C++, Python, Subversion, Java, Boost • Comments

I’ve worked at more than one organisation where a retrospective attempt has been made to set up a coding standard. This article discusses why these attempts were made and how they went.

What, No Coding Standards!?

When I say “a retrospective attempt”, I mean that plenty of code had already been written — over a number of years, in fact — with no existing coding standard in place. Is this a bad thing? Not necessarily. Joel Spolsky’s 12 point checklist on how to write better code is generally sound, and in particular I think he does well to not say:

“Do you have a Coding Standard, and does everyone follow it?”

In the cases I’m describing the code was in no way sub-standard. It worked well. Its success had caused the team to grow, with all the consequent problems, and in fact it wasn’t management who imposed a coding standard, but the developers themselves who decided they wanted one.

Loss of Freedom

A good coding standard shouldn’t be there to constrain developers or force them to comply to a particular coding style. In fact, most seasoned programmers are careful not to waste energy arguing about coding styles (which isn’t to say we don’t care, or don’t have opinions on such matters — it’s just that we prefer not to waste energy).

For this very reason, a coding standard can help. By drawing a line under arguments about where to place braces, how far to indent, what to call things, and then moving on, we allow ourselves to concentrate on solving more interesting problems. Even better, if everyone adopts a consistent style, it becomes easier to work with code written by colleagues.

The term “Coding Standards” suggests rules and red tape. It’s perhaps the most common term, which is why I’ve been using it, but I think guidelines are what are really required. In fact, as I’ll explain, we don’t really need guidelines since the experts have already written them for us. A “Style Guide” describing local conventions should be quite enough.

Ask the Experts

All too often a corporate coding standard reads as an attempt by a local expert to lay down rules on how to write good code: when to use exceptions, why to pass arguments by constant reference, when to use protected data members, etc. At best, this is a waste of effort, and, more likely (unless Herb Sutter or Scott Meyers happens to be your local expert), there’s a high probability these home-brewed rules will be wrong.

It’s far better to provide a well-stocked library than to attempt to write your own diluted imitations of Sutter and Meyers.

What Sutter and Meyers can’t do, though, is document your local coding style — by which I mean those finickity things such as what © copyright notice goes in a header file, where braces get placed, how far to indent, how to name things. That’s what goes in your Style Guide.

Small Stuff

The Style Guide, then, will comprise entirely of what Sutter and Alexandrescu refer to as “small stuff”, about which their specific advice is:

Item 0. Don’t sweat the small stuff.

— C++ Coding Standards, Herb Sutter and Andrei Alexandrescu

By this they mean:

Issues that are really just personal taste and don’t affect correctness don’t belong in a coding standard. Any professional programmer can easily read and write code that is formatted a little differently than they’re used to.

Does this imply that even a Style Guide isn’t worth writing? And if so, why ever did the team I was working on want one?

I agree with Sutter and Alexandrescu’s headline advice, but my take on it is slightly different: yes, small stuff isn’t worth fussing over; and yes, I’m capable of resetting my tabwidth to edit a file, and even of adopting the brace placement rules and naming conventions in force in that file — but it requires concentration and becomes tiresome. What if there are several conflicting styles in a single file? I prefer to work on a consistent code base, and so do most programmers I’ve worked with. So some sweating turns out to be necessary!

In this same section, Sutter and Alexandrescu manage to define a sensible naming convention in a single paragraph: this demonstrates the level of detail we’re looking for. An entire Style Guide should fit comfortably on a single page, otherwise it’s too fussy and won’t be adopted.

Re-Use

I hope we’ve agreed to resist the temptation to write our own feeble imitations of “C++ Coding Standards”, “Effective C++”, and similar. Out-sourcing this kind of thing is appealing. Surely we could also reuse a coding style we’ve seen elsewhere?

Language Conventions

Up to now I’ve avoided explicitly mentioned what programming language I’m talking about. If the language were Java, then defining our Style Guide really shouldn’t be an issue: we’d just cross-reference the Sun Java Programming Conventions, configure an Eclipse plugin to enforce these conventions, share the configuration and be done with it.

Similarly, Python has a reasonably well-defined preferred style — and its famous space-sensitivity unasks most questions about code layout.

If it’s C++ we’re talking about, the ground rules are less clear, and there’s a whole lot more syntax to fret about. Nonetheless, we could draw inspiration from the C++ Standard Library, which follows a consistent — if not formally documented — naming style. This is exactly what Boost has chosen to do, and indeed parts of Boost are already making their way into the C++ Library. Many of the Boost guidelines are specific to the Boost project, but we could sensibly extract the short sections on naming and layout to form the basis of our own Style Guide.

Use the naming conventions of the C++ Standard Library (See Naming conventions rationale):

• Names (except as noted below) should be all lowercase, with words separated by underscores.
• Acronyms should be treated as ordinary names (e.g. xml_parser instead of XML_parser).
• Template parameter names begin with an uppercase letter.
• Macro (gasp!) names all uppercase and begin with BOOST_.

Choose meaningful names — explicit is better than implicit, and readability counts. There is a strong preference for clear and descriptive names, even if lengthy.

…

• Use fixed-width fonts.
• Use spaces rather than tabs.
• Limit line lengths to 80 characters.

Of course, if we’re retro-fitting a style guide, it’s unlikely that we can just cut and paste the relevant sections of the Boost one. Another great site is Sven Rosvall’s Coding Standard Generator, which allows you to generate your own coding standard by filling out a few forms.

The Legacy Issue

What if, having got together our one page Style Guide, we find that, say, only 50% the codebase fits that style? This is a serious concern, and one which threatens the usefulness of the whole exercise.

A Style Guide is supposed to make things easier for new team members to pick things up — but if they discover little of the codebase follows the guide, then they’ll ignore it like everyone else seems to. Similarly, experienced team members will resent effort spent on writing a guide which only looks good on paper, and will ignore it too.

There’s no easy way to tackle this issue, but there are a few viable approaches:

1. Relax the style guide. By loosening it to accomodate everything, everything conforms.
2. Refactor the entire codebase to meet the accepted style.
3. When working on a file, first refactor it to meet the accepted style.

General C++ refactorings — to change the name of a class, for example — can be surprisingly difficult to automate and guarantee. The complexity of the language and its compilation model makes sure of that. Nonetheless, it can be done if the benefits are judged worthwhile. If you’re worried that changing code will break it, then you probably don’t have a good suite of regression tests: setting up and automating such a suite is far more important than code style issues.

Simple refactorings — to expand tabs to spaces, or to eliminate unwanted Subversion keywords — are easier to apply. Once done, they can be enforced using hook scripts.

In practice, a balance between the listed approaches combined with a good dose of common sense provides our only way forward. The Style Guide should be a living document which always reflects the current code base. As is so often the case, we can iterate to get where we want, starting from: step zero, no style guide, anything goes.