Microsoft StyleCop

StyleCop 4.4

jasonall — Thu, 06 May 2010 19:53:28 GMT

StyleCop 4.4 Beta 1 is now available for download from http://stylecop.codeplex.com/. This release provides full support for C# 4.0 syntax, and also provides integration into VS2010 and VS2008. We plan to leave this release in Beta for the next couple of months to flush out any remaining high severity bugs, finalize documentation, etc. The source code for this release is also available today at http://stylecop.codeplex.com.

StyleCop 4.4 comes with a number of improvements over 4.3.3, but also introduces a few breaking changes to the C# code object model. All existing custom rules will need to be rebuilt and redeployed for use with StyleCop 4.4!

In addition to a large number of bugfixes and other stability improvements, StyleCop 4.4 provides better support for rule suppressions. With StyleCop 4.3, only certain types of rules could be suppressed, while StyleCop 4.4 allows suppression of any rule type. In addition, 4.4 allows quick suppression of an entire class of rules. For example:

[SuppressMessage("Microsoft.StyleCop.CSharp.DocumentationRules", "*")]
public class MyClass
{
    public void MyMethod()
    {
    }
}

Rather than specifying the name and ID of a specific rule to suppress, this suppression attribute indicates that all rules in the DocumentationRules namespace should be suppressed. StyleCop will not report any documentation violations for this class or its members.

Please provide feedback on this release by filing issues at the StyleCop CodePlex site. Thanks!

StyleCop is going Open Source!

jasonall — Sat, 24 Apr 2010 01:06:00 GMT

I am very excited to announce that Microsoft has decided to take StyleCop Open Source under the MS-PL license. Specifically, this means that we will create a new project on CodePlex.com containing the full code base for StyleCop, and all future development on StyleCop will be done from that CodePlex site. Microsoft will continue to manage the StyleCop project, and Microsoft will be responsible for creating and releasing official signed builds. However, we will also take code submissions from the community, and you will have access to all of the source!

Since StyleCop was released publicly, there has been an overwhelmingly positive response from the C# development community. StyleCop has been adopted by many developers and dev teams worldwide. Many tools related to StyleCop have sprung up and StyleCop has been integrated into a number of different C# development environments. This has been excellent to see.

At the same time, many of you have complained about the slow pace of bugfixes and updates, about limitations in the license, and about some big things like a lack of support for VB.Net. Now you have the opportunity to solve these issues by writing the code, and making the tool better for everyone.

In a few weeks we will be taking the StyleCop CodePlex site live, and shortly after that we will be releasing StyleCop 4.4, which provides full support for C# 4.0, as well as a large number of bugfixes and other improvements. Stay tuned!

You’re welcome rickpastoor, you’re welcome

jasonall — Thu, 01 Apr 2010 15:17:37 GMT

http://twitpic.com/1cdur7

StyleCop for Visual Studio 2010

jasonall — Mon, 04 Jan 2010 15:38:00 GMT

We have just released a new StyleCop BETA which is identical to the previous release except that it adds the ability to integrate into the Visual Studio 2010 shell. After installing this release, you should see the familiar StyleCop menus showing up in both VS 2010 and VS 2008.

We plan to leave this release in BETA for a couple of weeks. If you decide to try it out, will you please let us know whether it’s working as expected for you?

You can pick up the Beta here: ~~https://code.msdn.microsoft.com/Release/ProjectReleases.aspx?ProjectName=sourceanalysis&ReleaseId=3754~~

[Update] The Beta has been upgraded to a full release, and can be downloaded from: http://code.msdn.microsoft.com/sourceanalysis/Release/ProjectReleases.aspx?ReleaseId=1425

Property Headers

jasonall — Tue, 11 Aug 2009 02:55:45 GMT

By default StyleCop comes with two rules which govern the summary documentation for properties, depending upon the types of accessors contained with the property. For example:

/// <summary>
/// Gets or sets the name of the customer.
/// </summary>
public string Name
{
get;
set;
}

In this example, StyleCop will require that the summary text starts with “Gets or sets” since the property has visible get and set accessors. In some cases, the set accessor has more limited access than the get accessor. For example:

/// <summary>
/// Gets the name of the customer.
/// </summary>
public string Name
{
get;
private set;
}

In this case, StyleCop requires the summary documentation to omit the “or sets” wording since public consumers of the property can only see the get accessor.

Unfortunately, it can sometimes be non-obvious whether the set accessor within a property is actually less accessible than the get accessor. For example, consider the case where a public property is contained within an internal class, and the set accessor has the internal keyword. In effect, both the get and set accessors have the same access level, because the entire class is internal. In this case, the summary documentation should refer to both the get and set accessors, since they have the same access level and can both be viewed by the same set of callers.

This can be a little confusing. In StyleCop 4.3.2, this behavior of this rule has changed slightly to avoid some confusion about when the “or sets” wording should be included. StyleCop now applies a series of rules to determine when the set accessor should be referenced in the property’s summary documentation. In general, these rules require the set accessor to be referenced whenever it is visible to the same set of callers as the get accessor, or whenever it is visible to external classes or inheriting classes.

The specific rules for determining whether to include the set accessor in the property’s summary documentation are:

1. The set accessor has the same access level as the get accessor. For example:

/// <summary>
/// Gets or sets the name of the customer.
/// </summary>
protected string Name
{
get;
set;
}

2. The property is only internally accessible within the assembly, and the set accessor also has the internal keyword. For example:

internal class Class1
{
    /// <summary>
    /// Gets or sets the name of the customer.
    /// </summary>
    protected string Name
    {
        get;
        internal set;
    }
}

internal class Class2
{
    public class Class3
    {
        /// <summary>
        /// Gets or sets the name of the customer.
        /// </summary>
        public string Name
        {
            get;
            internal set;
        }
    }
}

3. The property is private or is contained beneath a private class, and the set accessor has any access modifier other than private. In the example below, the access modifier declared on the set accessor has no meaning, since the set accessor is contained within a private class and thus cannot be seen by other classes outside of Class1. This effectively gives the set accessor the same access level as the get accessor.

public class Class1
{
    private class Class2
    {
        public class Class3
        {
            /// <summary>
            /// Gets or sets the name of the customer.
            /// </summary>
            public string Name
            {
                get;
                internal set;
            }
        }
    }
}

4. Whenever the set accessor has protected or protected internal access, it should be referenced in the documentation. A protected or protected internal set accessor can always be seen by an inheriting class, thus it should be included within the documentation. In the example below, the property is internal because it is contained within an internal class. However, the set accessor is protected, meaning that it can be seen by an inheriting class. The constructor of Class3 sets the value of the Name property. Thus, the property header should still refer to the set accessor.

internal class Class1
{
    public class Class2
    {
        /// <summary>
        /// Gets or sets the name of the customer.
        /// </summary>
        public string Name
        {
            get;
            protected set;
        }
    }

    private class Class3 : Class2
    {
        public Class3(string name)
        {
            this.Name = name;
        }
    }
}

Rule Suppressions

jasonall — Mon, 10 Aug 2009 22:06:03 GMT

Starting with StyleCop 4.3.2, it is possible to suppress the reporting of rule violations by adding suppression attributes within the source code. The syntax for these suppressions is similar to that for Visual Studio Code Analysis, or FxCop. For more information about Code Analysis suppressions, see the following article: In Source Suppressions Overview.

StyleCop rule suppressions are registered in code using the SuppressMessage attribute. The SuppressMessage attribute is a conditional attribute, which is included in the IL metadata of your managed code assembly only if the CODE_ANALYSIS compilation symbol is defined at compile time.

We recommend that you use in-source suppressions on debug or check-in builds, in order to eliminate the possibility of mistakenly shipping the in-source suppression metadata and compromising execution or performance because of the metadata bloat. Since StyleCop analyzes the source code directly, there is no need for these attributes to be compiled into the assembly.

The SuppressMessage attribute has the following format:

[SuppressMessage("Rule Category", "Rule Id", "Justification")]

Where:

Rule Category - The StyleCop rule namespace in which the rule is defined. For example, Microsoft.StyleCop.CSharp.DocumentationRules
Rule Id - The identifier for the rule, using the format shortname:longname. For example, SA1600:ElementsMustBeDocumented
Justification - The text that is used to document the reason for suppressing the message.

The SuppressMessage attribute also takes the following optional parameters. These parameters are completely ignored by StyleCop and do not need to be filled in for StyleCop suppressions.

Message Id
Scope
Target

SuppressMessage Usage

StyleCop violations are suppressed at the level to which an instance of the SuppressMessage attribute is applied. The purpose of this is to tightly couple the suppression information to the code where the violation occurs.

For example, a StyleCop SuppressMessage attribute placed on a class will suppress the rule for all contents of the class. The same attribute placed on a method will only suppress the rule within the method.

Global Suppressions

StyleCop does not support the notion of global suppressions or file-level suppressions. Suppressions must be placed on a code element.

Examples:

The following code suppresses the ElementsMustBeDocumented rule for the given class and all its contents:

[SuppressMessage("Microsoft.StyleCop.CSharp.DocumentationRules", "SA1600:ElementsMustBeDocumented")]
public class MyUndocumentedClass
{
    public void MyUndocumentedMethod
    {
    }
}

StyleCop update 4.3.2.1 is released

jasonall — Mon, 10 Aug 2009 20:57:00 GMT

I am pleased to announce that we’re released another build of StyleCop which includes multiple bugfixes as well as one significant new feature, the ability to insert in-code rule suppressions using the same attribute syntax as FxCop Code Analysis. For more information about rule suppressions, see this blog post: http://blogs.msdn.com/sourceanalysis/archive/2009/08/10/rule-suppressions.aspx

This release also fixes an issue accidently introduced into the last update which caused a bit of annoyance. It’s once again possible to “stack” your using statements such as:

using (Graphics g = this.CreateGraphics())
using (Form f = new Form())
using (Class c = new Class())
{
// Do stuff
}

Bugfixes:

89: Incorrect requirement to use string.Empty within const variable and field declarations
125, 217: Support for foreign characters
138, 139: Sorting issues with using directives
161: StyleCop incorrectly calculates accessibility of property set accessors and requires incorrect summary text.
171, 175, 192: Parsing error with complex generic types
173: Parsing error with fixed size array fields
184: StyleCop hangs indefinitely analyzing file
189: Incorrect requirement to use built-in type aliases within using directives
190: Allow using directives to be “stacked”. Only require curly brackets for the last stacked using directive.
218: Spacing issue
Fix for threading issue

Please upgrade to the new version at your earliest convenience:

Install link: https://code.msdn.microsoft.com/Release/ProjectReleases.aspx?ProjectName=sourceanalysis&ReleaseId=1425

Discussions: http://code.msdn.microsoft.com/sourceanalysis/Thread/List.aspx

Bugs: http://code.msdn.microsoft.com/sourceanalysis/WorkItem/List.aspx

StyleCop update 4.3.1.3 is released

jasonall — Thu, 12 Mar 2009 03:20:00 GMT

We have just released an update to StyleCop 4.3 which contains a number of bugfixes as well as a small number of new features. In particular:

Ability to use <include> tags within Xml header documentation to pull docs from external files.
Get accessor in property required to appear before set accessor
.generated.cs files ignored by default

Bugfixes:

18: Partial methods not handled correctly
31: Documentation rules should understand <include> element
56: Require get accessor before set accessor
63: When documenting a generic class, only allows <see cref="MyClass"/> and not <see cref="MyClass`1"/>.
70: Analysis of files in websites crashes Visual studio 2005 and 2008
74: SA1623 and SA1624 warnings appears in wrong situations
82: 'using' statement does not require curly brackets
88: Class without explicit access modifier marked as "public" instead of "internal"
90: False warning: SA1119: The line contains unnecessary parenthesis
93: Ignore .generated.cs files
94: Style Cop Crashes With A Blank Definition File
95: SA1101 isn't raised in method calls when the return value of the method is used.
98: VS crashed for webservices.
121: False syntax error with a nullable generic type reference.
124: LINQ operator "let" cause SA0101 when used with "condition ? true : false" syntax
151: False syntax error with a defaulted array.

Please upgrade to the new version, especially if you are hit by the crash in web projects.

Install link: https://code.msdn.microsoft.com/Release/ProjectReleases.aspx?ProjectName=sourceanalysis&ReleaseId=1425

Discussions: http://code.msdn.microsoft.com/sourceanalysis/Thread/List.aspx

Bugs: http://code.msdn.microsoft.com/sourceanalysis/WorkItem/List.aspx

Introducing StyleCop on Legacy Projects

jasonall — Tue, 11 Nov 2008 15:49:32 GMT

A number of people have asked for tips on rolling out StyleCop on a large, pre-existing codebase. This can prove challenging, since the tool will typically generate thousands of violations the first time it is run on existing code. For a large solution, this can make adoption of the tool a bit daunting.

On the other hand, it is relatively easy to comply with StyleCop when writing new code, especially for developers who are already familiar with the tool.

In this article I’ll describe a technique for doing a slow, staged rollout of StyleCop over your existing codebase. This technique has been used successfully by multiple teams within Microsoft, allowing them to adopt the tool in a controlled manner without generating a lot of noise up front. The general idea is to enable the tool for all of your solutions, but disable the tool from analyzing all pre-existing C# files. This provides the following advantages:

One day one, StyleCop will not generate any violations against your code, and will have zero measurable impact on your team.
Each time a new C# file is added to any project in your solutions, StyleCop will begin analyzing the code in that file. This will ensure that code in new files will be compliant from the start.
Over time, pre-existing files can be slowly cleaned up and introduced to StyleCop one by one.

This technique will allow your developers to slowly get used to the tool over time, without having to be confronted with thousands of StyleCop violations on day one.

The following steps explain how to introduce StyleCop over time, as described above. At this time, this technique is only possible when running StyleCop through MSBuild integration, meaning that StyleCop runs automatically whenever a build is performed.

1. The first step is to enable StyleCop MSBuild integration for each of your existing projects, as described here.

2. After StyleCop MSBuild integration has been set up, perform a build and verify that you can see StyleCop violations in the build output.

3. The next step is to exclude all pre-existing C# files from StyleCop. To do this, each csproj file must be edited to add an ExcludeFromStyleCop property for each C# file. Within the csproj files, edit each Compile tag as shown in the example below:

<Compile Include="File.cs"/>

Change this to:

<Compile Include="File.cs">
<ExcludeFromStyleCop>true</ExcludeFromStyleCop>
</Compile>

To make this easy, we have provided a sample tool which can do this for you. To use the tool, download the source code here, and build it in VS. This will produce an EXE called ExcludeStyleCop.exe.

Disclaimers: Keep in mind that this tool is provided as sample source code only, and will edit your project files! It is recommended that you make a copy of your source code before proceeding. This tool is only provided as a sample, and should be used at your own risk!

Running the tool with no command-line arguments will cause the tool to recursively find each C# project under the current directory, and add an exclusion tag for every C# file in every project. It is also possible to pass the path to a single csproj file on the command line, in which case the tool will only add exclusion tags for the files in that project.

4. Finally, perform a clean build and verify that there are no StyleCop violations in the build output. All C# files should be excluded now!

Whenever a new C# file is introduced to any of these projects, StyleCop will automatically begin to enforce the style of the code in that file each time the project is compiled. As more and more new files are introduced over time, developers will gain familiarity with the StyleCop rules.

As time allows, developers can clean up pre-existing files by removing the ExcludeFromStyleCop tag for a file, compiling, and cleaning up the StyleCop violations in that file.

StyleCop 4.3 SDK

jasonall — Fri, 29 Aug 2008 10:42:00 GMT

The SDK documentation for StyleCop 4.3 is now available for download, here: https://code.msdn.microsoft.com/Release/ProjectReleases.aspx?ProjectName=sourceanalysis&ReleaseId=1425

This documentation explains how to create and install custom StyleCop rules, how to integrate custom settings into the StyleCop settings dialog, and how to create a wrapper for hosting StyleCop in a custom build environment.