I can’t stress enough the importance of having a code convention in place before starting in any kind of software project.
What’s a code convention?
A code convention it’s about a team of developers agreeing on a standard
way to statically structure the code that will be part of the system they are building together . Note that it doesn’t cover any aspect of the software design, (coupling, cohesion, dependency management and so on) but rather focuses exclusively on how the body of the code is organized.
You may wonder, how is this valuable? Well, a convention has one primary goal that goes beyond plain esthetic: to improve the code readability by achieving consistency. Following a common standard will make it easier for the members of a team to work on each other’s code without the burden of having to mentally adjust to different coding styles.
Style matters
A code convention apply to all kinds of programming elements such as declarations, expressions and statements and it usually covers different aspects. Here is a non-exclusive list of what could be described in a coding standard:
- Naming (casing, use of prefixes/suffixes)
- Ordering (where different members are defined in the context of a class)
- Comments (where they should be placed and how they should be formatted)
- Spacing (between various syntactic elements such as punctuation)
Now, making a group of developers agree on how they should format their code on such a level of detail isn’t the easiest thing in the world. We all see programming code as a way of express our minds, and that includes also how many spaces there are between the parenthesis in a method call and the list of arguments.
Verbal agreement is not enough
Even if you do succeed in finding a middle ground that makes everybody happy (or sort of), you still need to make sure that the team will stick to what has been agreed on, without relying on tedious manual code review. Luckily there are tools out there that can automatically check code against a predefined coding convention.
One of them is StyleCop, a tool internally used by many teams at Microsoft, which has been repackaged and made freely available to the public under the Shared Source license.
The package contains a set of code format rules and a command-line program that checks all the source code files in a Visual Studio project against them and provides a compliance report.
The rules that are included out-of-the-box are the lowest common denominator among different verbally defined coding standard used by many teams at Microsoft who are developing on the .NET platform using C#.
Here is a brief overview of StyleCop’s features:
- Can only check C# code (support for other languages may be added in the future)
- It integrates with Visual Studio and MSBuild, which makes it possible to run validations on demand from the IDE or as part of a build.
- The set of rules to include can be controlled with a configuration file
- Includes a graphic configuration editor (called StyleCopSettingsEditor)
- It offers an SDK that allows to extend it by adding custom rules written as .NET classes
As mentioned, StyleCop includes a Visual Studio add-on, which allows to run it at any point in time against the currently opened project from a menu item.
By default the results of the validation are reported back to the user as warnings, but you have the option to have them show up as errors, if you care enough about consistency that is.
Configuration can be controlled via a Settings.StyleCop file, which is easily edited with the accompanying GUI editor.
StyleCop can also be run through a set of MSBuild tasks. All you have to do is include the target file that invoke the proper tasks in your custom build definition or Visual Studio project file:
<Import Project="C:\Program Files\MSBuild\Microsoft\StyleCop\v4.3\Microsoft.StyleCop.targets" />
Resources
You can download the latest version of StyleCop from MSDN including documentation and samples. If you need more information, here you can find a good tutorial on how to successfully integrate StyleCop in your .NET project.
/Enrico
McConnell’s Primary Technical Imperative
07/10/2008
I’ve recently picked up reading (again) my all-time favorite book about software development: Code Complete by Steve McConnell. The book was first published in 1993 and has been a timeless guide for anyone in this industry about the science and art of software development. A craftsman’s handbook, if you will.
In 2004 McConnell published Code Complete Second Edition, updated to cover the advancements in the software development practices that has happen
ed since the first release, like object-oriented programming, agile and test-driven development to name a few. All the code examples have also been updated to modern languages like C++ and Visual Basic, which substitute C and Pascal. However the main topic of the book remains unchanged, and that’s the whole point really. Software development concepts and best practices are a foundation whose principles are independent of specific technologies and programming languages.
Once I read the original Code Complete and now I am going through the Second Edition. My plan is to write here about some of the gems of wisdom kept in these tomes, based on the opinion that is extremely valuable to keep track of and share precious knowledge.
Last night I read about the fundamental concepts of developing software systems, and I was fascinated by one of them in particular. McConnell calls it “The Primary Technical Imperative”, and in order to explain it he refers to a famous essay published in 1987 by Fred Brooks called “No Silver Bullets – Essence and Accident in Software Engineering” (Computer, April 1987). In his paper Brooks argues that everything in the world as two kinds of characteristics, accidental and essential.
Accidental characteristics are those that can be attributed to a thing, but that do not define it. For example, a car could have a V8 engine and have 15 inch tires. These characteristics belong to that specific car but, if it had a different engine or tires it would still be a car. Essential characteristics, on the contrary, are those that are distinctive for a specific thing and cannot be eliminated. A car must have an engine and four wheels in order to be a car, otherwise it would be something else.
In the same way software development has both accidental and essential difficulties. The accidental difficulties are related to specific technologies and programming tools used to develop the software, and can be made easier through evolution. For example, the difficulty in programming with assembly language has been addressed by creating higher level programming languages and compilers. Also programmers no longer have to write code in basic text editors, but instead can take advantage of integrated development environments with aids like syntax highlighting and statements auto-completion.
However, the essential difficulty in software development comes from the goal of software itself, which is to solve real world problems with the aid of the computer.
In order to do that, we need to represent reality in a way that is manageable by a computer, and this is exactly where the essential difficulty lies:
To define and constraint the unpredictable and approximate interactions that happen among things in the real world, in order to make them fit inside a predictable and exact computer program.
Developing software is therefore a matter of managing the complexity that arises when bringing order and structure to the chaos of reality.
With this principle in mind, it becomes obvious why all software development practices traditionally aim at achieving control and predictability. Their goal is to prevent complexity from getting out of hands.
Modern practices like agile development take a different approach. They recognize that change is an essential characteristic of reality and therefore, instead of fighting it by putting limits and constraints, they adjust the process of developing software to cope with change by simply becoming more flexible. But that’s for a whole other story.
/Enrico
