In this recipe, we will see how to customize file headers to avoid StyleCop violations, and how we can use Visual Studio templates and snippets to make our life easier while developing.
For this recipe, you will need to have:
StyleCop 4.7 installed
Visual Studio 2008 or higher
Note
StyleCop doesn't use a lot of rules for headers. Basically, it requires the following things: the file name, a copyright, a company name, and a summary.
Let's try to make a LGPL header compliant with StyleCop. As there's no advice on how to integrate the Version 3.0, we will stick with the header proposed in Version 2.1 and which can be viewed at http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
The only requirements of the LGPL license header is to give one line to describe the project, the year of the project, and the author that wrote it (I will use the company name as the author). So the file header should look something like the following:
// <summary> // {one line to give the library's name and an idea of what it does.} // </summary> // <copyright file="{File}" company="{Company}"> // Copyright (C) {year} {Company} // // This library is free software; you can redistribute it and/or // modify it under the terms of the GNU Lesser General Public // License as published by the Free Software Foundation; either // version 2.1 of the License, or (at your option) any later version. // // This library is distributed in the hope that it will be useful, // but WITHOUT ANY WARRANTY; without even the implied warranty of // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU // Lesser General Public License for more details. // // You should have received a copy of the GNU Lesser General Public // License along with this library; if not, write to the Free Software // Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA // </copyright>
Having this license is great in itself; however it will be quite boring to add it manually in each file we create. In order to automate it, we will create a Visual Studio template. This will help you to have consistent file headers during your project at a minimal cost. To begin with, we will create a new library project, and modify
Class1.csby adding the previous LGPL header we made. Now, we have to modify the line of the summary section to comply with our project description; then we will modify the first copyright lines to enable visual studio to change text automatically. The first two lines of the copyright section have to be changed like this:// <copyright file="$safeitemname$.cs" company="$registeredorganization$"> // Copyright (C) $year$ $registeredorganization$
In this code, we just introduce some Visual Studio template parameters:
safeitemname: This is the name you provide when you add a new item to your project.year: This is the year you added the file.registeredorganization: This is the name of the company you provided during your Windows installation. It can be found in the registry under theHKLM\Software\Microsoft\Windows NT\CurrentVersion\RegisteredOrganizationkey.
Now that we have our model for the template ready, we have to export it.
Click on the File menu and select Export Template.
Select the
Class1.csitem, and then click onNext.Add the default assemblies you want to include in the template, and then click on Next.
Modify the template name and template description to suit your taste and click on Finish.
The template is now available in the My templates section when you create a new file.
In this recipe, we see a way to include your own licensing section in headers. If your needs are not so specific that they include a particular license, you can have a look at this site http://vstemplates.codeplex.com/, which provides some basic templates for visual studio compatible with StyleCop.
In the following paragraph we will see two others topics meant to help you manage the headers of your code files.
While templates are ideal for new files, you might need to apply your templates to old work. Visual Studio provides numerous ways to do so. You can at least rely on snippets or macro.
Snippets are quite easy to create. They are in fact a simple XML file with a piece of code containing parameters. Let's create it for the LGPL license:
<?xml version="1.0" encoding="utf-8"?>
<CodeSnippets xmlns="http://schemas.microsoft.com/VisualStudio/2005/CodeSnippet">
<CodeSnippet Format="1.0.0">
<Header>
<Title>Add LGPL License</Title>
<Author>Franck LEVEQUE</Author>
<Description>Add LGPL License to a file</Description>
<Shortcut>copyright</Shortcut>
</Header>
<Snippet>
<Declarations>
<Literal Editable="true">
<ID>Description</ID>
<ToolTip>Insert here your project description </ToolTip>
<Default>Project description</Default>
</Literal>
<Literal Editable="true">
<ID>ClassName</ID>
<Default>ClassNamePlaceHolder</Default>
</Literal>
<Literal Editable="true">
<ID>Company</ID>
<Default>Company</Default>
</Literal>
<Literal Editable="true">
<ID>year</ID>
<Default>Year</Default>
</Literal>
</Declarations>
<Code Language="csharp" Kind="" Delimiter="$"><![CDATA[// <summary>
// $Description$
// </summary>
// <copyright file="$ClassName$.cs" company="$Company$">
// Copyright (C) $year$ $Company$
//
// This library is free software; you can redistribute it and/or
// modify it under the terms of the GNU Lesser General Public
// License as published by the Free Software Foundation; either
// version 2.1 of the License, or (at your option) any later version.
//
// This library is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
// Lesser General Public License for more details.
//
// You should have received a copy of the GNU Lesser General Public
// License along with this library; if not, write to the Free Software
// Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
// </copyright>]]></Code>
</Snippet>
</CodeSnippet>
</CodeSnippets>The first part of the snippet named Header describes what will be displayed in the snippet menu; I added a Shortcut element to be able to use it by typing copyright followed by two tabulations. The two really important sections are the Declarations section and the Code section. As you can see the Code section is simply the code of the LGPL we created in the first part. We just replaced each variable name with a parameter name surrounded by $. The Declarations section contains a definition of all the parameters you use in your snippet code. Each Literal element contains an Editable attribute specifying that you can edit the parameter, an ID element that is the variable name surrounded by $ in the code and a default value.
Your snippets usable in C# are generally located in Documents\Visual Studio 2008\Code Snippets\Visual C#\My Code Snippets.
Note
To edit snippets more easily, you can use Snippet Editor. It can be downloaded at http://snippeteditor.codeplex.com/.
StyleCop can enforce a specific company name and a copyright text in the copyright section. This might be useful if you want to be sure all the files of your project have the same copyright information. To do so, you need to go in the StyleCop settings in the Company Information tab.
The Company Name field corresponds to the company attribute of your copyright tag, whereas the Copyright field refers to the content of the copyright tag.