使用StyleCop.Analyzers进行代码审查

为什么要进行代码审核？

1. 提早发现代码中的BUG，避免将BUG带到生产环境
2. 极大的提高软件质量，以及可维护性
3. 统一代码规范、提高可读性，减少新加入成员的熟悉时间
4. 加速个人和团队的成长，知识和经验的积累

StyleCop.Analyzers介绍
　　代码审查的方式有很多种，大体上分为人工审查和工具审查，这里我们只说工具审查。

StyleCop是微软的一款代码审查工具，使用它可以检查代码中的各类静态编程规范错误，从代码注释，代码布局，可维护性，命名规范，可读性等各方面对代码规范性进行检查。
重要的是，其规则可以自定义，可以屏蔽掉不适用于特定项目的规则，甚至可以自定义开发适用于各自项目的规则，它有3种使用方式：

1. 作为VS扩展使用
2. 作为ReSharper插件
3. 与MSBuild集成

由于技术原因StyleCop对于新C#语法的解析越来越困难，因此StyleCop以后仅会进行稳定性维护功能上不会有重大升级。
如果你使用VS2015与C# 6及以上建议使用StyleCop.Analyzers，它是基于Roslyn编译平台重写的。

使用StyleCop.Analyzers
　　本文以ASP.NET Core项目为例，其它项目大同小异。
使用StyleCop.Analyzers最简单的方式是添加NuGet包，您可以直接在VS里安装StyleCop.Analyzers 或 命令安装 Install-Package StyleCop.Analyzers

添加完成后您需要对它进行配置，配置文件有2个

1. 规则集文件（例如：rules.ruleset），其作用为：
   • 开启或关闭特定规则
   • 配置指定规则满足时引发的错误级别，例如：错误、警告、信息等
2. stylecop.json文件，其作用为：
   
   • 配置指定规则的详细参数，例如.cs文件头的copyright内容
   • 微调某些规则的行为

下面看一个规则集文件的示例：

<?xml version="1.0" encoding="utf-8"?>
<RuleSet Name="Rules for StyleCop.Analyzers" Description="Code analysis rules for StyleCop.Analyzers.csproj." ToolsVersion="14.0">
  <Rules AnalyzerId="StyleCop.Analyzers" RuleNamespace="StyleCop.CSharp.NamingRules">
    <Rule Id="SA1300" Action="Error" />    
  </Rules>
</RuleSet>

其中SA1300表示规则ID，您可以在这里找到StyleCop.Analyzers内置的所有规则ID：https://github.com/DotNetAnalyzers/StyleCopAnalyzers/tree/master/documentation
Action="Error"表示满足此规则时让编译器产生错误，效果如下图：

Action可以取值：None | Error | Warning | Info | Hidden

规则集定义的详细信息请参见：https://msdn.microsoft.com/zh-cn/library/dd264996.aspx

下面看一个stylecop.json文件的示例：

{
  "$schema": "https://raw.githubusercontent.com/DotNetAnalyzers/StyleCopAnalyzers/master/StyleCop.Analyzers/StyleCop.Analyzers/Settings/stylecop.schema.json",
  "settings": {
    "documentationRules": {
      "documentInternalElements": false,
      "documentExposedElements": false
    }
  }
}

其中documentInternalElements表示可见性为internal的接口或类等是否要求写注释，默认为true，我们这里改为了false
具体详细信息请参见：https://github.com/DotNetAnalyzers/StyleCopAnalyzers/blob/master/documentation/Configuration.md

接下来需要将规则集、stylecop.json文件与项目关联起来，在project.json文件的buildOptions中增加additionalArguments，例如：

"buildOptions": {
    "emitEntryPoint": true,
    "xmlDoc": true,
    "additionalArguments": [ "/ruleset:../../StyleCop/rules.ruleset", "/additionalfile:../../StyleCop/stylecop.json" ]
  }

如果内置规则无法满足您的需求您还可以自定义审查规则，然后在规则集里配置，这里先埋个坑下篇再具体讲。