Adopting C programming conventions
|Click here for more info about next ESC.|
This paper (from the Embedded Systems Conference class of the same name) discusses some of the problems found in a lot of code today and suggests how they can be avoided. There are many ways you and your embedded development team can improve code quality and in the process, become significantly more productive. Techniques are presented to organize project directories, naming files, laying out code, naming variables, functions, and more. Examples are presented for C but most of the concepts apply to other languages.
|This article also appeared in May 2011 ESD print issue. Click image to go to digital edition.|
The topic of coding conventions is controversial because we all have our own ways of doing things. One way is not necessarily better than the other. However, it's important that all team members adopt a single set of rules and that these rules are followed religiously and consistently by all participants. The worse thing that you can do is to leave each programmer to do his or her own thing. Such an undisciplined activity will certainly lead to chaos. When you consider that close to half of the development effort of a software-based system comes after its release, why not make the sometimes unpleasant task of supporting code less painful?
In this paper, I'll share some of the conventions I've been using for years and I hope that you'll find some of them useful for your own organization. I urge you to document your own conventions because it makes life easier for everyone, especially when it comes to supporting someone else's code.
One of the first rules to establish is how files are organized. Do you place all the source files in a single directory or do you create different directories for different pieces? I like to use a structure similar to that shown in Table 1.
Click on image to enlarge.
Each product (such as ProdName) has its own directory under PRODUCTS\. If a product requires more than one microprocessors then each has its own directory under ProdName\. All products that contain a microprocessor has a SOFTWARE\ directory. The SOURCE\ directory contains all the source files that are specific to the product. If you have highly modular code and strive to reuse as much code as possible from product to product, the SOURCE\ directory should generally only contain about 10% to 20% of the software which makes the product unique. The remaining 80% to 90% of the code should be located in the \SOFTWARE directory (discussed later). The DOC\ directory contains documentation files specific to the software aspects of the product (such as specifications, state diagrams, flow diagrams, and software description). The TEST\ directory contains product build files (such as batch files, make files, and IDE project) for creating a test version of the product. A test version will build the product using the source files located in the SOURCE\ directory of the product, any reusable code (building blocks), and any test-specific source code you may want to include to verify the proper operation of the application. The latter files generally reside in the TEST\ directory because they don't belong in the final product. The PROD\ directory contains build files for retrieving any released versions of your product. The other directories under ProdName\ are provided to show you where other disciplines within your organization can store their product-related files. In fact, this scheme makes it easy to backup or archive all the files related to a given product whether they're related to software or not.
The \SOFTWARE\ directory is where you could store all reusable, non-product specific files. I call these building blocks, and each contains its own documentation.