Coding with Style

By Rik Heywood
14 February, 2002

I have been programming professionally for well over a decade now. Over that time I have worked at several companies and about half of them made use of a coding style guide. Working in the half that used a style guide was far more pleasant. Working in areas of the project that you were not familiar with was much easier, new hires were able to get up to speed quicker and lots of common types of bugs were eradicated. So what makes a good programming style guide?

Before we get into the details I think it would be a good idea to say a couple of things first.

1. Style guides are in the realm of the religious war. Programmers can get very upset and animated when discussing style guides. Some feel that style guides are unnecessary. Some are willing to kill or die to avoid using tabs or some other minor point in the guide. If you are thinking of implementing a style guide in your company then make sure you get everyone that will be effected to agree on what goes in and what stays out of the style guide.
2. In this article I will not be telling you what your style guide should be. Whether you CapitaliseEachWord in variable names or use_underscores is a decision you will have to make with the rest of your team. What I am going to talk about is why you should bother and how much detail you should go into.

The Benefits

First off, you will need to ask yourself why you want a style guide in the first place. If you have no style guide now, and everything is working fine, then you had better have a good reason for messing with your developers. If you work in a large organisation with multiple teams, and you want to be able to re-use code between teams, then it makes sense that the source code should be in a style that everyone understands. If you are a two man team, then you can probably be more flexible about things.

At Synaptic Soup, we give Cipher's source code to developers that have licensed it from us. Because of this, I feel that it is important that all of Cipher's source code looks like it belongs together and is consistent in the way it approaches and solves problems. A style guide is critical for achieving this.

Areas to consider for inclusion

A style guide can cover a lot of ground, from specific rules for how the source code should be laid out, to rules governing which features of the programming language can be used. Below is a list of items that are frequently specified in style guides. Pick and choose the items that you think will be appropriate for your team.

Bracing and Indentation Style. Where should the curly brackets go? Should they always be used, or only when needed by the language?

Naming Conventions. What are the rules for naming functions, classes, global variables, local variables, structure and types. What do you think the following names are...

• CRectangle
• m_Widget
• WidgetWeight
• flux_capacitance
• world_RayIntersection
• pItem
• widget_t

You will probably think some of those are very sensible names, and other are plain madness. If you don't have a rule about what to use where, expect madness to prevail.

Tab Style. Some teams don't like tabs and insist that everyone set up their editors to replace tabs with spaces. Others hate spaces and want tabs to be used whenever possible. Should tabs be equivalent to 2 spaces? How about 4 spaces, or maybe 8, or even the clearly insane 3 spaces?

Function Comments. A block comment before every function can help to break up the source code and make it clearer where one function ends and another begins. They also provide a convenient place to describe exactly what a function is supposed to do and why. Another view is that they are a waste of space, that end up getting out of date and providing miss-information. Maybe you want to use an automatic documentation compiler like Doxygen, in which case these function comments need to follow strict rules.

Compiler Warnings. Which compiler warnings are acceptable and which should be treated as errors. Most of the teams I have worked on have treated any warning the compiler produces by default (e.g. not level 4 warnings in Visual C++) to be an error, and must be fixed before the code is considered ok.

Development Quirks. Each project has its own unusual quirks and requirements that developers on the team need to know about. For example, in Cipher all text is UNICODE, so people have to be careful not to forget that when using text. You might have your own custom serialisation code that has certain requirements of classes that want to use it (must derive from a specific base class, or have a default constructor etc). It is also common to have rules about when and where it is acceptable to call platform specific functions. Most of the projects I have worked on have had a platform independent section of code and a platform specific section of code, and no one wants to see calls to MessageBox() appearing in the middle of the platform independent stuff. Document all these rules so you can put them in your style guide where people can see them.

Error Handling. Does your code base have a fancy error handling system? How do you use it? Are functions expected to be able to accept garbage on their inputs and handle it, or can they make assumptions and use asserts to validate those assumptions in debug builds. What should a function do when it encounters an error? Throw an exception? return false? return LogError("Widget expired")? Whatever it damn well likes? Make sure developers know.

Programming Language Usage. If you are using a big complex programming language like C++, you may have to specify which features of the language can and can't be used. Maybe you will be porting your code base to a platform that fails to implement some features of your chosen programming language (or implements them badly enough to render them useless). Are you allowed to use STL or templates in your C++ code? Should you use cout << i; or printf("%d", i);?

Use of Custom Types. Does your project define its own versions of int, unsigned int etc and when should you use them? Are you allowed to use Windows types (DWORD, LPCSTR etc) or should you use project equivalents?

Bad habits. It is also useful to list things that have historically caused problems in the past, and should therefore be avoided in the future. For example, don't use gotos, one statement per line, always check pointers for NULL before dereferencing them, always flange a widget via the FlangeManager class, etc.

Enforcement

There is no point putting in all the effort of actually writting a style guide if you are just going stick it on the project web site and forget all about it. It is critical to make sure that team members adopt the style guide. It is inevitable that you will meet with some resistance, but if the team was not invloved in the creation of the style guide, the resistance will be massive.

The first couple of weeks of the style guide's life will be the hardest for everyone, as they try and learn all the rules and adapt their programming style to match. Some of the rules that seemed such a great idea when you were writing the style guide may turn out to be turkeys in the field, so be prepared to revise the rules based on feedback during those first few weeks. Eventually the details will stabalise and everyone will settle on a style that works for the team.

It is important to remember that most of the decisions in a style guide are fairly arbitary. Whether you use tabs or spaces doesn't really matter a whole heap at the end of the day, so if everyone on the team hates the decision, be prepared to change it. Remember, the style guide was made to improve the productivity of your devleopers and the stability of your software. If everyone is complaining and doing their own thing, then you will gain nothing.

After you have started to use a style guide, don't forget to keep it up to date. I once worked at a company that made use of a style guide, but sadly it was very old. The company mostly consisted of large teams working with C++, but the style guide was written when the company was much younger. Back then, all programming was done using C in small teams of 1 or 2 programmers. The rules just got in the way and caused problems, until they were brought up to date.

What is the right way of doing it then

Tabs of course!

If you have a style guide where you work, why not tell us which parts of it work and which parts of it don't. Maybe the rest of use can learn something.