Implementing a Source Code Standard: a necesity

You will have noticed that we are really getting into managing and controling our software process at my daytime job. In this description of our progress I will talk to you about implementing code standards.

Why coding standards

Before talking about the why of coding standards, I must explain what we use as a definition of coding standards:

Coding standards enforce a uniform look for your source code by specifying code styles. These style guides include, among other, naming conventions, code layout, file and folder layout, etc…

Coding standards are not restricted to code style guides, but also provide coding style and design guidelines for programming constructs like exception classes, DLL modules, etc…

Some people detest coding standards because it presumably does limit their creativity. Personally I really favour coding standards because they make code written by several people readable. I know this is the classic argument in favour of coding standards but it is the truth. If your creativity in programming is determined by being able to add underscores to class member variables, like “_count”, instead of using “m_count”, I think you are low on creativity. What’s more, if your creativity is limited by using some proved patterns, I think you’re ignorant.

As an example, everyone has their own decorating style for prefixes and capitalizing of class names and standardizing on one style used in a group of developers really benefits the readability of the code. Of course, choosing the style to use is often arbitrary and the subject of debate and flame wars.

Second, standards allows new people to get up and running quickly. This is true for the design guides especially. Our code standard has a section on implementing DLL’s which states to use interfaces and factory functions. If someone new starts in our group he is handed our standard as obligatory reading (and memorizing) and thus knows how to write a DLL compliant with our groups “way of doing things”. The design guides are constantly tweaked and new ones are added, thus allowing senior members to pass on their experience about how to do things and more importantly how not to do things to junior members.

What others are doing

We’ve written a source-code standard for the languages we’re using, which are C++ and C#. As always I went wandering the web, reading books for information on standards and to see how other people do it. Here’s what I’ve come-up with:

Articles of interest

Books of interest

What we ended up doing

I will not publish our complete coding standard here. Not that it is a secret, but it would make this post much too big. I will tell you the sections that are in it, so that you have a general idea of what is included in it.

First we have a chapter on naming conventions, which mostly describes, well, naming conventions. It is divided in following sections

  • General naming conventions (example: names are always in the English language) 
  • Module naming conventions (example: unit-tests for modules must have the name of the module with suffix “UnitTest”, for automatic execution by Nant scripts).
  • File naming conventions (example: files have the name of the class they contain).
  • Namespace naming conventions (example: usage of pascal or camel case)
  • Type naming conventions (classes and interfaces, example: interfaces are preceded by a capital “I”, classes have no prefix, thus no “C”).
  • Member naming conventions (variables, methods, method parameters, example: use “m_” prefix for member variables).
  • Category naming conventions for classes (example: exception classes have a suffix of “Exception”).
  • Language specific naming conventions (example: naming conventions for template parameters in C++).

The second chapter is about code lay-out. It has following sections:

  • IDE configuration (example: indention by tabs or spaces).
  • Folder layout (example: where is the deployment folder).
  • File layout (example: order of includes in C++)
  • Block layout (example: length of code-lines is maximum 100 characters).
  • White spaces (example: write “i = j” instead of “i+j”).
  • Statements (example: do not put multiple statements on one line).
  • Class layout (example: put public methods first in the header for C++).

Most of the stuff in chapters 1 and 2 is rather arbitrary: that is, most people agree on prefixes for member variables, but some use “m_”, like “m_someMember”, while others use “_”, like “_someMember”. These are arbitrary choices in that there is no real “wrong” or “correct” method. It’s more a matter of taste and fashion.

Following chapters are more in the design area and give guidelines and best practices on the use of language constructs and good object oriented design.

Chapter three is about coding styles and mostly regulates language constructs:

  • General coding style (example: Complex conditional expressions must be avoided).
  • Structures (example: never use structures in C++ where classes should be used).
  • Classes (example: member variables are always private)
  • Functions and methods (example: always use constant references for input parameters).
  • Exception handling (example: use exception handling instead of return values).

Chapter four is about documenting code:

  • What to document.
  • Which tools to use (Doxygen and NDoc).

Following four chapters discuss respectively modules, executables, static and dynamic libraries:

Module Design Guide:

  • What are the types of modules? (executable, static library, dynamic library)
  • What common files must always be present (example: history.xml which contains the history of changes of the file, and it’s layout)
  • What are the obligatory configurations that must be present (“Release” and “Debug”)

Executable Design Guide:

  • What is the standard output folder for the resulting executable. 
  • What common files must always be present (example: a Nant build file tailored to executables) 
  • Configuration properties of the IDE project file (example: where to look for library files).

Static Library Design Guide:

  • What is the standard output folder for the resulting library file. 
  • What common files must allways be present (example: a Nant build file tailored to static libraries) 

Dynamic Library Design Guide:

  • The design guide for dynamic libraries is very thorough because we want our libraries to expose all their functionality by interfaces. So the design guide is basically a stripped down version of COM interfaces: just the virtual table layout and factory functions, not the dynamic querying or reference counting.
  • What is the standard output folder for the resulting executable. 
  • What common files must always be present (example: a Nant build file tailored to dynamic libraries) 
  • Configuration properties of the IDE project file (example: where to look for library files).

And of course there is the continuous improvement and tweaking. The standard gets updated rather frequently, as we gain experience with the languages and tools we use. This is mainly because we also include design guide lines and when we gain experience with certain constructs, we include best practices for them in our coding standard.

Future Improvement

Most of our coding standard could be implemented by using adapted wizards for Visual Studio. Things like file headers stating the programming language, the developer name, file name, date of creation, or obligatory files by module type, etc… could be automated using adapted templates for Visual Studio projects.

In the future we might split the standard in two parts:

  1. A first part for pure naming conventions, code layout and setup stuff, which will stabilize rather quickly.
  2. A second part for design guides and best practices, which gets extended as we gain experience and “explore new horizons”. 

We are currently looking at extending it with guidelines for user interfaces and database stuff: naming conventions, design and obligatory tables (The obligatory tables are tables describing the version of your database, which can then be queried by our software).

Advertisements

5 thoughts on “Implementing a Source Code Standard: a necesity

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s