使用StyleCop.Analyzers进行代码审查

时间:2020-12-08 23:22:01

为什么要进行代码审核?

  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"表示满足此规则时让编译器产生错误,效果如下图:
使用StyleCop.Analyzers进行代码审查

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" ]
}

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