ALM Practices Part 6: Code Analysis & Guidelines

What is it?
Coding guidelines, or coding standards if you will, are documents consisting of rules and recommendations on the use of C# in enterprise systems. They deal with code layout, naming guidelines, the proper use of the .NET Framework, tips on writing useful comments and XML documentation, and often also include guidance on proper object-oriented design. Visual Studio’s Static Code Analysis (a.k.a. FxCop) can automatically verify a majority of those rules and recommendations by analyzing the compiled assemblies. You can configure to do that at compile time or as part of a continuous or daily build. The Aviva Solutions Coding Guidelines for C# 3.0 and 4.0 adds additional rules and recommendations and provides a list of Code Analysis rules that are applicable for Line-of-Business applications and frameworks.

Why would you do it?
Because not every developer

• is aware of the potential pitfalls of certain constructions in C#.
• is introduced into certain conventions when using the .NET Framework (e.g. IDisposable)
• is aware of the impact of using (or neglecting to use) particular solutions on aspects like security, performance, multi-language support, etc.).
• knows that not every developer is as capable in understanding an elegant, but abstract, solution as the original developer.

What’s the usual thing to do?
Ensure that all code, including unit tests, complies with your coding guidelines and the Code Analysis rules selected for your project.

How do you do that?

• Ask all developers to carefully read the Coding Guidelines at least once. This will give them a sense of the kind of guidelines the document contains.
• Make sure there are always a few hard copies of the Quick Reference close.
• Include the most critical coding guidelines on the checklist and verify the remainder as part of your Peer Review.
• Decide which CA rules are applicable for your project and write these down somewhere, such as your TFS team site. The C# Coding Guidelines site on CodePlex offers Visual Studio 2010 rule sets for both Line-of-Business applications and more generic code like frameworks and class libraries.
• Add a custom Code Analysis Dictionary containing your domain- or company-specific terms, names and concepts. If you don’t, Static Analysis will report warnings for (parts of) phrases that are not part of its internal dictionary.
• Configure Visual Studio to verify the selected CA rules as part of the Release build. Then they won’t interfere with normal developing and debugging activities, but still can be run by switching to the Release configuration.
• Add the verification of the CA rules part of your Continuous or Daily Build.
• Add a rule to your team that the first one who comes in the office in the morning will check the build for CA warning and will make sure somebody (not necessarily himself) solves it as soon as possible.
• Add an item to your project checklist to make sure all new code is verified against CA violations, or use the corresponding Check-in Policy if you want to prevent any code from violating CA rules at all.
• ReSharper has an intelligent code inspection engine that, with some configuration, already supports many aspects of the Coding Guidelines. It will automatically highlight any code that does not match the rules for naming members (e.g. Pascal or Camel casing), detect dead code, and many other things. One click of the mouse button (or the corresponding keyboard shortcut) is usually enough to fix it.
• ReSharper also has a File Structure window that shows an overview of the members of your class or interface and allows you to easily rearrange them using a simple drag-and-drop action.
• Using GhostDoc you can generate XML comments for any member using a keyboard shortcut. The beauty of it, is that it closely follows the MSDN-style of documentation. However, you have to be careful not to misuse this tool, and use it as a starter only.
• Consider reading the book Clean Code: A Handbook of Agile Software Craftsmanship by Robert C. Martin. It provides excellent guidance on writing elegant and simple code that is easy to maintain and to extend. His ideas have evolved into a new quality standard maintained by many well-known community members.