用StyleCop規範團隊代碼

前言

編碼風格，每一個人都是有不一樣的特色，風格各異，並且一我的在不一樣的時期，編碼風格的差別也多是很是大的，比如學生時代，剛工做的時候，工做一段時間後等。

在一個團隊中，或一個項目中，若是出現了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的控制檯程序以後，大體就是下面的樣子。能夠看到是沒有任何警告的。

經過Nuget安裝StyleCop.Analyzers，或直接在csproj裏面加下面的內容。

<ItemGroup>
   <PackageReference Include="StyleCop.Analyzers" Version="1.1.1-rc.94">
     <PrivateAssets>All</PrivateAssets>
   </PackageReference>
</ItemGroup>

在回到Program.cs，立刻就能夠看到有波浪線了~~

這個時候咱們須要狠一點，把項目的全部警告級別的提示都當成錯誤來看待。

<PropertyGroup>
    <!-- other... -->
    <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
</PropertyGroup>

加了這個以後，編譯就立馬出錯了。

在編譯不經過時，仍是ERROR級別的錯，只能乖乖的去改了。

按照提示，一個個修改以後，仍是有一個SA0001的錯誤提示。

要修復這個問題，須要參考這個文檔 SA0001.md

啓用一下生成XML文檔，同時加幾個禁止顯示的警告便可。

<PropertyGroup>
    <!-- other... -->
    <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
    <!-- 加下面2行,處理SA0001 -->
    <GenerateDocumentationFile>true</GenerateDocumentationFile>
    <NoWarn>$(NoWarn),1573,1591,1712</NoWarn>
</PropertyGroup>

這個時候再build，就不會有錯誤了。

對於這麼簡單的一個空項目，都有很多要修改的地方，就能夠知道，默認的規則是比較嚴格的。那麼咱們有沒有辦法避免應用某些規則呢？答案是確定的。

咱們能夠經過添加代碼分析規則集來自定義。

有兩個方式添加，一個是直接添加新建項；一個是經過修改分析器裏面的規則集嚴重性，修改後會自動生成。

下面咱們經過修改兩個規則來體驗一下。

一個是不想要上面的頭部(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一下項目，就能夠正常經過了。

既然能夠本身定義，那麼就必然有這樣一個問題，每一個人可能都會想把本身的習慣放開，這樣的話，這個規則就是一個透明的存在了！！

換句話說，必需要有一些硬性規定，必需要有一些取捨。咱們能夠向某些開源項目借鑑，同時在他的基礎上作簡單的添加刪除，我的以爲應該能夠適應大多數的狀況了。

下面放出幾個以爲不錯的參考。

• Autofac 目前我就是以這個爲基礎的
• EntityFrameworkCore

在代碼分析規則集的基礎上，還能夠用Stylecop.json來微調某些規則的行爲。

當把SA1633恢復以後，提示的第二個選項就是添加Stylecop.json配置文件

添加以後，還要在csproj裏面作設置

<ItemGroup>
    <AdditionalFiles Include="stylecop.json" />
</ItemGroup>

關於Stylecop.json的具體配置，能夠參考Configuring StyleCop Analyzers，這裏不繼續展開。

除了上面的辦法，還能夠經過安裝擴展StyleCop來處理。

安裝後，右擊項目的時候就能夠看到StyleCop相關的菜單。

總結

在團隊內保持同樣的編碼風格，並能在開發過程當中糾正相應的錯誤，這是編寫可維護和可讀代碼的重要一步，一樣也是代碼審查的重要一步！

固然，在團隊內推行這類規範，仍是要多多聽取團隊成員的意見，也要定時檢查規則是否須要更新，畢竟時代在進步！只要達成一致，就是好規則，就應該要遵照。

StyleCop是一個很不錯的工具，用的好就是利器。能夠把它和cli模板項目相結合，這樣建立的新項目就都「內嵌」了同樣的規則了。

友情提示，在老項目添加這個要慎重，否則會有一陣陣酸爽。

相關文章

• 代碼審查工具StyleCop
• StyleCop: A Detailed Guide to Starting and Using It
• Automated, portable code style checking in .NET Core projects