Found at: http://publish.ez.no/article/articleprint/18

Coding Standards - Part 1 - Introduction

Publishing date: 31.10.2000 19:46

Coding standards define a standard for the look and feel of your code. This is helpful to most projects, and to some it is a necessity. Especially in open source projects.

About this article

The goal of this and the following articles is to show how coding standards will improve a development project. We use the C++ coding standard of eZ systems as an example of such a standard, but the concepts mentioned here are valid for and can be applied to many programming languages. We also use it for PHP development, wherever applicable.

What is a coding standard?

A coding standard is a set of rules describing how your code should look, which features of the programming language you will use and how, and possibly which tools should be used to write the code. It can of course be as specific as you want it to be.

Why is it good?

People are different. We like different things, wear different clothes, and use different styles when coding. This is fine as long as we just write small programs and scripts for ourselves. When many people collaborate on a project, the differences in coding style will lead to disagreements and poor readability which will hamper the cooperation and thereby the effectiveness of the project. An example of such disagreements is the simple, but widespread problem of indentation. How much indentation should be used? Where? Should we use spaces or tabs? There are probably as many opinions on this as there are programmers, and most of them are dead sure that their way is the right one. (The correct way of indenting C++ code is 4 spaces per level and no tabs, if you were curious. And, by the way, keep those curly brackets on a separate line, or you'll face at least seven years of bad luck and core dumps.) These problems are obvious in many open source projects where perhaps hundreds of people from all around the world develop software together, but it will soon become a problem in small projects and corporate environments as well. Even when you just write your own programs you will run into difficulties sooner or later, unless you use some kind of coding standard.

It's natural

Your personal taste in programming is in itself a coding standard. You don't randomly use constants with upper and lower case, you probably don't mix different styles of while-loops and you definitely don't use a different indentation for each line of code. (At least I hope you don't, for your own sanity's sake.) Standards are natural. Unfortunately, arguing about them is, too. Always remember, when you join an open source project it is common sense to follow that project's standards. If you try to force your standards on others you'll lose your write privileges faster than fast. That's one of the great advantages of starting a project, you get to do it the right way - your way.

Our example

I'll try not to talk too much about how great this standard is (it is of course the best possible standard, but, as I said, I'll try not to talk too much about that) but rather to stress the importance of having standards at all. Almost any standard is better than no standard. And again, this is a C++ example, but the principles and concepts here are valid for many, if not most programming languages.

Files

All filenames are lowercase. Header files are suffixed with .hpp, implementation files with .cpp. The advantages of using all lowercase filenames on a case-sensitive system like Linux is obvious. The use of the .hpp suffix enables us to differ between C and C++ header files.

Each cpp/hpp pair contains only one class, unless we are using private classes. If a header file contains constants and declarations that don't need external includes, as well as other declarations that do need external includes, then dividing this file to avoid too many dependencies could be a good idea.

An implementation file that has to be written differently for different platforms, is to be split into one file containing platform-independent code, and one file per platform containing platform-dependent code.

In the next issue of this article we'll be moving along to macros, indentation and brackets.

| Back to normal page view |