Coding Standards and the default Visual Studio 2008 templates
I’ve never really been one for strict coding standards, and I’m not the first to admit that commenting out code is a generally an afterthought for me. The problem is that working in a small development team means the pressure is on to deliver quickly, and if you leave commenting the code to the end of the project, more often than not, another project lands on your desk – which clearly is far more exciting than documentation, so the code remains uncommented and forgot about.
I feel no shame in admitting the above (now) as I have changed my ways, and I am vigorously commenting my code as it is written. This is all thanks to StyleCop and FxCop, two great tools which analyse your C# code and assemblies and enforce style and consistency rules.
One issue I have though, is that although the rules set out in these code analysis tools have been specified by Microsoft, and that it is the standards they now strive to achieve, the default templates shipped with Visual Studio (including 2008) fail the analysis terribly.
Take the standard C# class template:
using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
namespace ClassLibrary1
{
class Class1
{
}
}
Running this through StyleCop issues the following warnings:
SA1600: The class must have a documentation header.
SA1633: The file has no header, the header Xml is invalid, or the header is not located at the top of the file.
SA1400: The class must have an access modifier.
SA1200: All using directives must be placed inside of the namespace.1
SA1200: All using directives must be placed inside of the namespace.
SA1200: All using directives must be placed inside of the namespace.
SA1200: All using directives must be placed inside of the namespace.
This is not unique to class templates, in fact every single template I use (Classes, Interfaces, Forms, User Controls, Components etc. all fail the StyleCop rule engine , so working on a large project means that every single item you add to your project is more than likely going to fail the validation and needs restructuring.
The Desired Result
I’m going to carry on talking about the class template, as it’s probably the most common. Sorting out all of the validation errors that StyleCop reported, results in the following class.
//
// Copyright (C) 2008 The Wight Stuff. All rights reserved
//
namespace net.thewightstuff
{
using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
///
/// TODO: Class description goes here
///
public class Class2
{
///
/// Initializes a new instance of the Class2 class
///
public Class2()
{
// TODO: Implement default Class2 constructor
}
}
}
The key things that have changed are the following:
· Added my standard copyright header to the file.
· Moved all of the using statements into the namespace and sorted them alphabetically
· Added a class documentation header
· Added an access modifier (public) to the class
· Added a default constructor with documentation header
Doing this to every class which I create in a solution is not really going to get me into the right mindset of constant documentation, so we need to change the default class template that is shipped with Visual Studio.net
Modifying the standard templates
The standard template folder is held in the following registry key:
HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\VisualStudio\9.0\VSTemplate\Item\UserFolder
Which is typically C:\Program Files\Microsoft Visual Studio 9.0\Common7\IDE\ItemTemplates
The folder structure employed here is in general
Template Folder\language\locale
Each item in the add new item dialog is contained in corresponding zip file in this folder structure. Therefore, the default C# template is located at (on my installation):
C:\Program Files\Microsoft Visual Studio 9.0\Common7\IDE\ItemTemplates\CSharp\Code\1033\Class.zip
Inspecting this zip file yields the following files:
The file we are mainly interested is the Class.cs file, which contains the code that is placed into the new file when it is created. The Class.vstemplate file contains other items, such as the text that is displayed in the dialog, the icon used, and any project references that should be added to the project if this item is added. This article is not going to touch the .vstemplate file.
The default class template looks like the following if loaded into visual studio:
using System;
using System.Collections.Generic;
$if$ ($targetframeworkversion$ == 3.5)using System.Linq;
$endif$using System.Text;
namespace $rootnamespace$
{
class $safeitemrootname$
{
}
}
This file is obviously parsed by the IDE and the relevant tags replaced. I am no means an expert in what all the tags mean but they seem pretty self explanatory.
$if$ ($targetframeworkversion$ == 3.5)using System.Linq;
$endif$
This part checks the target framework of your assembly of project and if it .net 3.5, then automatically adds System.Linq to your using statements
This is the namespace of the assemby that you are adding the file to
This is the name of the file you have added, e.g. Class1
So, without changing it too much, I have amending this class file to the following:
//
// Copyright (C) 2008 The Wight Stuff. All rights reserved
//
namespace $rootnamespace$
{
using System;
using System.Collections.Generic;
$if$ ($targetframeworkversion$ == 3.5)using System.Linq;
$endif$using System.Text;
///
/// TODO: Class description goes here
///
public class $safeitemrootname$
{
///
/// Initializes a new instance of the $safeitemrootname$ class
///
public $safeitemrootname$()
{
// TODO: Implement default $safeitemrootname$ constructor
}
}
}
The next step is to save this file, and update the Class.zip file with the new file.
You can then go through and update all the classes that you commonly use.
Once you are ready, you will need to update the template cache in visual studio before it will start to use your new templates. To do this, at the command prompt, navigate to your visual studio installation Common7\IDE folder, and execute the following:
C:\Program Files\Microsoft Visual Studio 9.0\Common7\IDE>devenv.exe /InstallVSTemplates
Voila! After this has processed, your new templates are ready to use. Enjoy.
16/12/2008 14:47:00
Category
C#
Back