欢迎您访问程序员文章站本站旨在为大家提供分享程序员计算机编程知识!
您现在的位置是: 首页  >  IT编程

用StyleCop规范团队代码

程序员文章站 2022-06-30 13:24:15
用StyleCop来规范团队代码,通过一个简单的控制台程序来演示如何使用StyleCop.Analyzers ......

前言

编码风格,每个人都是有不同的特点,风格各异,而且一个人在不同的时期,编码风格的差异也可能是非常大的,好比学生时代,刚工作的时候,工作一段时间后等。

在一个团队中,或一个项目中,如果出现了n种风格,这个可能就是比较头疼了,尤其是风格差异很大的时候。

一个项目一种风格或许还可以接受,如果一个项目风格都不一样,那就有点难受了,就更不用说整个团队的了。长久来看,团队之间,难免会有人员的调动,所以统一整个团队的编码风格还是很有必要的。

统一了编码风格会带来什么好处呢?下面列出几点

  1. 便于代码审查
  2. 新人(新同事/跨项目组同事)接手不会觉得杂乱无章
  3. ...

下面来先看看本文的重点stylecop。

什么是stylecop?

这里引用*的介绍

stylecop is an open-source static code analysis tool from microsoft that checks c# code for conformance to stylecop's recommended coding styles and a subset of microsoft's .net framework design guidelines. stylecop analyses the source code, allowing it to enforce a different set of rules from fxcop (which, instead of source code, checks .net managed code assemblies). the rules are classified into the following categories:

  • documentation
  • layout
  • maintainability
  • naming
  • ordering
  • readability
  • spacing

简单理解,开源的静态代码分析工具,用来检查代码是否符合推荐的编码风格。

它的开源地址: https://github.com/stylecop/stylecop

其在readme的最后,建议我们(使用visual studio 2015或更高版本的开发人员)使用的是stylecopanalyzers

所以,后面我们用到的是它,stylecop规则基于.net编译器(roslyn)的实现。

下面通过一个示例来介绍它的简单使用。

示例

当我们新建一个.net core的控制台程序之后,大致就是下面的样子。可以看到是没有任何警告的。

用StyleCop规范团队代码

通过nuget安装stylecop.analyzers,或直接在csproj里面加下面的内容。

<itemgroup>
   <packagereference include="stylecop.analyzers" version="1.1.1-rc.94">
     <privateassets>all</privateassets>
   </packagereference>
</itemgroup>

在回到program.cs,马上就可以看到有波浪线了~~

用StyleCop规范团队代码

这个时候我们需要狠一点,把项目的所有警告级别的提示都当成错误来看待。

<propertygroup>
    <!-- other... -->
    <treatwarningsaserrors>true</treatwarningsaserrors>
</propertygroup>

加了这个之后,编译就立马出错了。

用StyleCop规范团队代码

在编译不通过时,还是error级别的错,只能乖乖的去改了。

按照提示,一个个修改之后,还是有一个sa0001的错误提示。

用StyleCop规范团队代码

要修复这个问题,需要参考这个文档 sa0001.md

启用一下生成xml文档,同时加几个禁止显示的警告即可。

<propertygroup>
    <!-- other... -->
    <treatwarningsaserrors>true</treatwarningsaserrors>
    <!-- 加下面2行,处理sa0001 -->
    <generatedocumentationfile>true</generatedocumentationfile>
    <nowarn>$(nowarn),1573,1591,1712</nowarn>
</propertygroup>

这个时候再build,就不会有错误了。

用StyleCop规范团队代码

对于这么简单的一个空项目,都有不少要修改的地方,就可以知道,默认的规则是比较严格的。那么我们有没有办法避免应用某些规则呢?答案是肯定的。

我们可以通过添加代码分析规则集来自定义。

有两个方式添加,一个是直接添加新建项;一个是通过修改分析器里面的规则集严重性,修改后会自动生成。

用StyleCop规范团队代码

下面我们通过修改两个规则来体验一下。

一个是不想要上面的头部(sa1200),一个是using可以在命名空间外面(sa1633)。

下面是示例代码。

<?xml version="1.0" encoding="utf-8"?>
<ruleset name="demo analyzer rules" description="analyzer rules for demo." toolsversion="15.0">
  <rules analyzerid="stylecop.analyzers" rulenamespace="stylecop.analyzers"> 
    <!-- using statements must be inside a namespace -->
    <rule id="sa1200" action="none" />
    <!-- the file header is missing or not located at the top of the file -->
    <rule id="sa1633" action="none" />    
  </rules>
</ruleset>

同时,还要修改csproj文件

<propertygroup>
    <!-- other... -->
    <treatwarningsaserrors>true</treatwarningsaserrors>
    <!-- 加下面2行,处理sa0001 -->
    <generatedocumentationfile>true</generatedocumentationfile>
    <nowarn>$(nowarn),1573,1591,1712</nowarn>
    <!-- 加下面这行,自定义代码分析规则集 -->
    <codeanalysisruleset>..\test.ruleset</codeanalysisruleset>
</propertygroup>

去掉代码的头部,和把using放到外面,再build一下项目,就可以正常通过了。

用StyleCop规范团队代码

既然可以自己定义,那么就必然有这样一个问题,每个人可能都会想把自己的习惯放开,这样的话,这个规则就是一个透明的存在了!!

换句话说,必须要有一些硬性规定,必须要有一些取舍。我们可以向某些开源项目借鉴,同时在他的基础上做简单的添加删除,个人觉得应该可以适应大多数的情况了。

下面放出几个觉得不错的参考。

在代码分析规则集的基础上,还可以用stylecop.json来微调某些规则的行为。

当把sa1633恢复之后,提示的第二个选项就是添加stylecop.json配置文件

用StyleCop规范团队代码

添加之后,还要在csproj里面做设置

<itemgroup>
    <additionalfiles include="stylecop.json" />
</itemgroup>

关于stylecop.json的具体配置,可以参考configuring stylecop analyzers,这里不继续展开。

除了上面的办法,还可以通过安装扩展stylecop来处理。

用StyleCop规范团队代码

安装后,右击项目的时候就可以看到stylecop相关的菜单。

用StyleCop规范团队代码

总结

在团队内保持一样的编码风格,并能在开发过程中纠正相应的错误,这是编写可维护和可读代码的重要一步,同样也是代码审查的重要一步!

当然,在团队内推行这类规范,还是要多多听取团队成员的意见,也要定时检查规则是否需要更新,毕竟时代在进步!只要达成一致,就是好规则,就应该要遵守。

stylecop是一个很不错的工具,用的好就是利器。可以把它和cli模板项目相结合,这样创建的新项目就都“内嵌”了一样的规则了。

友情提示,在老项目添加这个要慎重,不然会有一阵阵酸爽。

相关文章