Friday, February 29, 2008

Coding Standards: The Real Importance

A lot of times people think of coding standards as the place where you put the brackets in a code block. Aesthetical standards are nice to have to give consistency to the code. But, the real importance of coding standard is about establishing a mechanism to detect common mistakes and possible errors that can happen while writing code.

Not a believer on coding standards my self, I got my eyes opened when I read the book C++ Coding Standards: 101 Rules, Guidelines, and Best Practices by Sutter and Alexandrescu. As the title suggests, coding standards are not only about naming conventions, indentation, or brackets, but about rules, guidelines, and best practices that you should follow while writing code.

It is nice to define how methods of a class should be named, where you place the brackets after an 'if' statement, or the number of spaces you should use to indent code. This type of things give a consistency to the code that once you get use to them, they make easier to read code written by others. Actually, I have a very strong opinion about how all these things should be done, as I am sure any developer does. But enforcing this type of silly rules, it is not going to help you to achieve your ultimate goal of writing robust quality software. Furthermore, they might have an adverse effect because enforcing these rules can set your team against any type of standard and not follow more important rules.

The rules, guidelines, and best practices defined by your coding standard should focus on common language pitfalls, and the measures to prevent them. More experienced programmers in your team should identify these pitfalls and define the best way to avoid them. Newcomers and less experienced members of the team will benefit from all this documented knowledge, and the quality of your program will increase.

Code reviews should focus, not only on the correct implementation of the feature being reviewed, but also in the correct use of your coding standard. Reviewers must enforce every submission follows the rules, guidelines, and best practices, and when a decision being made violates your coding standard, the decision should be properly documented in the code.

There might be some aesthetical rules or guidelines in your coding standard. Things like separating public, protected, and private members into distinctive blocks can be helpful to understand the implementation of a class, and you should define them in your coding standard if you wish. The capitalization of members or whether you should use a distinctive prefix for data members of the class can help readability and should be part of your standard. Getting too wrapped-up on things like bracket placement, spaces after parenthesis, or size of indentation can be counterproductive.

You should identify which aesthetical guidelines are actually going to improve the readability of your code. You should concentrate on which guidelines will help to increase the quality of your code because they will make it easier to understand, and which ones will not really matter. You should pick-up your battles because programmers are very opinionated about this type of things, and you do not want any obstacles that will prevent the adoption of your coding standards.

For a long time, I was not a believer in coding standards until Sutter and Alexandrescu open my mind. At the time, C++ was my main programming language, and their book help me a lot back then. Now, I am using other languages, and I wish there was a similar book written for them. I recommend you read the book, even if you are not a C++ programmer because some of the rules will still apply to any modern language (or at least to languages like Java and C#). Some others will not apply, but the book will show you what a good coding standard looks like.

Find the glitches of your programming language, search for the most common pitfalls and mistakes people make when writing code in your language of choice and document the correct way to avoid them. That is a good start for your coding standard. But most important, make sure your team follows what your coding standard defines.


No comments: