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.

 

Technorati Tags: Programming,Software Development,Coding Standards,Best Practices,Rules,Guidelines

What Should Be Part Of Your Automated Build

Personal reasons have kept me away from this blog for a very long time. It has been longer than I expected, but it seems that finally things are settling down, and I would like to resume this fine and fun practice. And what better way to do it than to resume from where I left.

I started this blog writing about a series of strategies you must define in any software development project. I wrote about the importance of a source code management strategy, and the reasons why you should define a documentation strategy. Now, it is time to talk about your automated build process.

Let me start by saying, if you do not have an automated build process you are doomed to fail. The reasons are simple. Automation will help you to reproduce every necessary step to build your product as many times as you need removing human factors that most likely lead you to failure. People tend to make mistakes; scripts do not. When an automated build process fails is indicative of some human error not a script making a mistake (assuming your script works). Therefore, you want to have a complete automated build process.

An automated build process means different things to different people. In my mind, it only has one definition: the set of automated steps that grab everything needed for your application from you source repository, and operates in it to compile, test, and package your application. Yes, you read it all right; compile, test and package your application.

An ideal build process downloads all the required files from your source repository, compiles and links the source code to create your binaries, runs all your automated tests, and packages your application files into your deployment package. One single click, one single scheduled task launches your build process and spits a package that you can release to your customers at the end of it. So let us talk about what your build process needs to do.

Your Source Repository Is The Beginning Of It All

Every project file should be in your source repository. This includes your source code, documentation source, application data and content, and build scripts. The only file that is not part of your repository is the one and only script that triggers everything, and this script should only download the source and invoke your build process.

Many people see the build process as a separate entity from the product. This is a big mistake. Your build process is going to change in the same way your project changes. New dependencies are added, new files are added to the application, new application content is added to your project. The same way all those files reflects a particular state of the application, your build scripts reflect a particular state that allows you to build your project at a specific point in time. Keeping the project files and the build process separate will only add a maintenance burden to your process, so it is always better to keep them together.

Obviously, It Build Your Binaries

Needless to say, your build process is going to produce the binaries that your application needs. But the process of building the binaries needs to do more than just that.

Binaries will need to be versioned in a consistent way with each new build. Company information might need to be embedded into the binaries, and the binaries might need to be signed. Your documentation and help files might also need to be compiled.

Make sure you build every configuration of the files you need to ship or that are used internally and for every platform you support. This means you should build your release configurations, as well as your debug configurations.

This is what most people understand as the build process. To me, this is just the first step of a bullet-proof build process.

Run Test Automation

Once you have all the files you need for your application, it is wise to test them. If you have automated tests, and you should, run them against your newly created binaries. Make this test run part of your build process to insure your application is tested to some extent with every build.

This does not mean you should not rely on the manual testing your QA department does. As a matter of fact, you are insuring your application runs and can be tested by QA. You will eliminate problems where your application seems to compile but crashes on start-up. Including your automated acceptance tests into your build process will alleviate the headaches QA gets when the build is broken.

Package Your Application

Your automated build process should generate the images for all your deployment packages. Ideally, it will also cut the CD or DVD you intent to ship, but most of the time, and ISO will do.

If you are at the end stages of your project when you are building your release candidates, you can use the packages you produced to ship your product once QA has given the OK.

Many people does not include the ISO generation as part of the build process, and they manually create it afterwards. Guess what, they make mistakes, and they have to recreate the ISO's more than once. Not a good idea when you are in a hurry to ship.

Make Sure You Can Execute All Previous Steps Independently

It is a good idea to isolate each of the previous steps and design them so that they can run by themselves. This will give you a lot of flexibility, and there will be times when you will need this.

You want the ability to just run the compilation steps to create a check build that runs with every check-in against the source repository. This will validate the state of your source with every changes and will allow you to catch errors quicker.

There will be times, especially close to release, where you will only want to re-master your application to include an updated license agreement, help file, or content file. You can achieve this if the application packaging is design in a way that does not depend on the compilation or testing of your application.

You may want to test your application every few hours to insure that changes have not affected stability. In this case, you will want to get the latest source, compile it, and run your automated tests.

Of course, once or twice a day, you want to run through the entire process to validate your production build. This does not mean you are going to release it or give it to QA, but you want to make sure your whole process works.

Notify Your People

It is inevitable. Your build process is going to break. Someone is going to check-in code that does not compile, files are going to be changed or deleted, dependencies are going to change. When this happens, you want to notify immediately to the right people.

A broken build process should be the first priority of your team, and no further development should be done (or at least checked-in into your source repository) until is fixed.

An automated build process is the best way to insure your application is stable at al times. It is the quickest way to get feedback about the changes that are going on in your project. And, you need to build your application to be able to release it. If you rely on manual steps to build your application, things will fail when you least want them to fail. Automation will help you to reproduce the same steps over and over again, and insure that you end up with a working product at the end of each cycle.

Technorati Tags: Software Development,Build Process,Agile Development,Programming