StyleCop

Earlier in the week, thanks to The Morning Brew #101 I downloaded and installed Microsoft Source Analysis for C# (aka StyleCop).

As a fan of FxCop I was interested to find out what this had to offer and so ran it on some new code that Bruce and I have been working on for a Madgex ILP project

Running StyleCop

I ran it against one (already FxCop'd) file, and came up with the following deviations from the rules (displayed in a new "Source analysis" window):
SA1101: The call to m_source must begin with the 'this.' prefix to indicate that the item is a member of the class.
SA1200: All using directives must be placed inside of the namespace
SA1308: Variable names must not start with 'm_'
SA1502: The constructor must not be place on a single line. The opening and closing curly brackets must each be placed on their own line.
SA1600: The class must have a documentation header.
SA1600: The constructor must have a documentation header.
SA1600: The field must have a documentation header.
SA1600: The property 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.

SA1101 and SA1308 go hand in hand to my mind. We use m_ to indicate that the item is a class level field, and is the underlying element for a property. Using "this." instead also shows that this is what is happening. So, I don't have a problem with this at all.

SA1200 is a weird one, this differs from the templates and almost all sample code I've seen on MSDN etc. There have been quite a few blog posts about this.

SA1502 is only ususally done within our code when inheriting the constructor from the base class or this class, i.e. either
public NewClass(string name)
  : base(name) {}
or
public NewClass(string name, string description)
  {
    this.myName = name;
    this.myDescription = description;
  }
public NewClass(string name)
  : this(name, null) {}

Changing {} to be
{
} makes little difference and may improve readability.

All the variations of SA1600 are fine - documentation is useful, and using the summary sections is as good a way as any. I did get some subsequent warnings when I only used a one word description
SA1630: The documentation text within the summary tag does not contain any white space between words, indicating that it most likely does not follow a proper grammatical structure required for documentation text.
or a very short description
SA1632: The documentation text within the summary tag must be at least 10 characters in length. Documentation failing to meet this guidelines most likely does not follow a proper grammatical structure required for documentation text.

SA1633 is tricky, there is some documentation explaining the rules that a file header must adhere to, which indicates that the minimum file header must be:
//<copyright file="Widget.cs" company="Sprocket Enterprises">
// Copyright (c) Sprocket Enterprises. All rights reserved.
// </copyright>
This is probably the rule I dislike the most. I don't have a problem with file headers, but I don't think that the style of those headers should be enforced. Also, not all code actually is done via a Company - it could be personal code, in which case author would be more appropriate.

Changing the settings

There is a settings editor which is included in the Program Files folder, which can be started from the command line as:
C:\Program Files\Microsoft Source Analysis Tool for C#>SourceAnalysisSettingsEditor Settings.SourceAnalysis
where Settings.SourceAnalysis is the predefined file created/installed as part of the installation process.

This editor allows settings to be altered/changed to provide additional or more appropriate checks. Rules can be switched off - so I can prevent SA1633 from being reported to me. Company information and copyright text can be added so that the Header checking verifies against known and predefined information.

The settings editor can also be accessed from with the Visual Studio IDE by right-clicking on the project and selecting the menu option "Source Analysis Settings". This then created project level settings which is useful when wanting to change the settings on a project by project basis. To my mind, I'd rather set it on a machine level, and use the same settings across all of my projects - my use of a tool like this would be to ensure consistent styling, and changing the settings on a per project level stops this. There is an element of merging that can be acheived, by selecting the "Settings File" tab in the editor but how this works in practice I haven't, as yet, had chance to investigate.

The .Net Afficionado has some useful links to find out more information and Love The Dot has an article about creating custom rules.