好代碼是管出來的——C#的代碼規範

　　代碼是軟件開發過程的產物，代碼的做用是經過編譯器編譯後運行，達到預期的效果(功能、穩定性、安全性等等)，而另一個重要做用是給人閱讀。對於機器來講只要代碼正確就可以正確的運行程序，可是人不一樣，若是代碼編寫混亂就會對代碼閱讀形成障礙，致使代碼沒法維護，甚至會致使代碼重構等高成本活動，因此規範代碼勢在必行。

　　本文從如下幾個方面介紹代碼規範以及相關工具。

• .Net代碼規範簡介
• 代碼格式規範
  • 命名規範
  • 佈局規範
  • 註釋規範
• 代碼使用規範
• 經常使用的代碼規範工具
• 小結

.Net代碼規範簡介

　　文章開始提到過代碼是給人看的，代碼規範的目的在於建立一個統一的規範來保持代碼的整潔，這樣有利於提升代碼的可維護性，但除此以外還能夠將一些代碼的最佳實踐也做爲規範的一部分，這樣還能夠提升代碼的性能和安全性。
　　通常來講.Net的代碼規範主要有：代碼格式規範、代碼使用規範，前者保證代碼可讀性後者保證代碼執行效率和安全性。

代碼格式規範

　　代碼格式規範主要的目的是統一代碼編寫格式，避免開發人員獨特的代碼編寫方式，以便於項目的全部開發人員能快速的閱讀其餘人員開發的代碼，代碼格式規範主要有如下幾個方面：

　　注：除如下規範外，對於一個工程來講應該還有工程結構規範(也能夠理解爲代碼目錄結構規範)，工程結構規範可能因項目不一樣而不一樣，可是統一規範能夠提升代碼查找效率和開發效率(團隊新成員不會再疑惑代碼應該放哪裏)。

命名規範

　　命名規範主要涉及命名空間、類型、接口、屬性、方法、變量等相關命名，其主要規範有：

• 使用Pascal(單詞首字母大寫)命名方式對命名空間、類型、枚舉類型、枚舉值、事件、屬性、方法、常量進行命名。

　　例：public class PersonManager {}

• 使用Camel()命名方式對參數、變量、字段進行命名。

　　例：private string userName;
　　禁止使用縮寫，除URL、IO等能達成共識的縮寫除外，使用縮寫可全大寫。
　　例：System.IO；

• 接口以I作爲前綴進行命名。

　　例：public interface IConvertor {}

• 抽象類以Abstract爲前綴或者以Base爲後綴進行命名。

　　例：public abstract class PersonBase {}

• 異常類型以Exception爲後綴。

　　例：public class CustomException {}

• 在對任何東西命名時須要使用有意義的名稱，而且保證單詞拼寫正確以及語法正確，避免使用拼音(地名等通用拼音除外)。

　　例： public string Name {get; set;}
　　反例： public string N {get; set;}

佈局規範

　　佈局規範的目的是使代碼變得整潔，提升代碼可讀性，其主要規範有：

• 代碼縮進爲4個空格。

　　左右花括號必須獨自一行，括號內容爲空時除外：
　　例：public void WriteLog(string log)
　　　　{
　　　　　　Console.WriteLine(log);
　　　　}

　　　　public void EmptyMethod(string log) {}

• 括號的使用：
  • if/for/while/do等關鍵字後面與左括號直接須要加空格：

　　　　　　if (x == 1)

• • 運算符左右須要加空格：

　　　　　　a = c + b;

• 單行代碼限制120個字符，超長處理方式：
  • 第二行相對第一行縮進4個空格，從第三行開始無需縮進。
  • 運算符及方法調用的「.」須要跟隨換行，但逗號不須要。

　　　　　　例：WebHost.CreateDefaultBuilder(args)
　　　　　　　　　　.UseStartup<Startup>()
　　　　　　　　　　.Build();
　　　　　　　　App.Method(a
　　　　　　　　　　+ b,
　　　　　　　　　　c);

註釋規範

　　註釋用來對編寫的代碼進行說明，包括功能說明以及實現說明，這樣能夠大大的提升程序的可讀性，另外規範的註釋還能夠經過工具來生成相應的API文檔，C#的註釋規範有如下幾種：

• 類註釋

　　例：/// <summary>
　　/// This is a Entity Class for Post.
　　/// </summary>
　　public class Post

• 屬性及方法註釋：

　　/// <summary>
　　/// Get post with id
　　/// </summary>
　　/// <param name="id">post's identity</param>
　　/// <returns>post instance</returns>
　　public Post GetPostById(int id)

• 代碼單行註釋：

　　//this is a single line comment

• 代碼多行註釋：

　　/*
　　this is comment1
　　this is comment2
　　*/

代碼使用規範

　　代碼的使用規範，或者說是代碼編寫的最佳「實踐」(固然優良的格式規範也是一種最佳實踐)，它們是根據代碼的實現/運行原理以及特定的應用場景進行實踐的最佳方案，這些方案的使用除了能夠提升代碼的可讀行外，還能夠減小程序Bug、提升程序性能及安全性，如如下幾個方面：

• 使用語言特性

　　this：使用this區分類型中的屬性與變量、靜態成員，能夠提升程序可讀性。
　　var：適當的使用var能夠提升開發效率且不影響程序可讀性，如在不知道返回值具體類型或者不須要知道類型的時候。
　　反例：

　　

　　本例來自：https://weblogs.asp.net/dixin/csharp-coding-guidelines-4-types

• 字符串內插(string interpolation)：字符串內插是C#6.0的特性，使用字符串內插能夠提升程序可讀性：

　　例：

　　

• 異常
  • 當程序出現與預期不符時應該拋出異常讓程序上游處理。
  • 儘量使用C#中內置的異常類型。
  • 捕獲異常必須處理。
  • 獲取指定異常而非統一使用Exception。
• 安全準則

　　參考：https://docs.microsoft.com/zh-cn/dotnet/standard/security/secure-coding-guidelines
　　更多規範可參考：https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/inside-a-program/coding-conventions
　　代碼使用規範是一個普遍的話題，除了以上一些通用的規範以外，還能夠對OOP以及開發框架等方面根據實際狀況制定規則，使用統一的規範進行開發可讓代碼變得更加容易管理。

經常使用的代碼規範工具

• Visual Studio

　　VS是很是強大的IDE，在衆多功能中固然不會缺乏對代碼規範的支持。

• StyleCop

　　StyleCop是一個代碼分析工具，StyleCop有兩個版本StyleCop和StyleCop Analyzers，前者適用於VS2010-VS2017全部版本，它的原理是在編譯時對代碼進行分析，而StyleCop Analyzers僅支持VS2015+,它基於.Net的roslyn編譯框架實現的，它支持開發時對代碼進行實時分析(再也不須要等編譯)。
　　StyleCop:https://github.com/StyleCop/StyleCop
　　StyleCop Analyzers:https://github.com/DotNetAnalyzers/StyleCopAnalyzers

• Resharper

　　Resharper是jetbrains公司開發的一個VS收費插件，它不只包含了代碼分析，還具有了代碼生成、編譯、測試、調試等功能。
　　VS2017與Resharper的功能比較https://www.jetbrains.com/resharper/documentation/comparisonMatrix_R2018_1_vs2017.html

• EditConfig

　　EditConfig是一個跨編輯器/IDE的代碼風格一致性維護工具(協議/插件)，如今VS2017已經支持EditConfig

• DocFx

　　DocFx是一個API文檔生成工具，使用DocFx能夠快速的搭建一個程序使用、及API文檔，樣式可參考：
　　DocFx教程：http://dotnet.github.io/docfx/tutorial/docfx_getting_started.html
　　API文檔：http://dotnet.github.io/docfx/api/Microsoft.DocAsCode.html

小結

　　本文主要介紹了C#中的編程規範，並將規範分爲了兩個類型，分別是格式規範和使用規範，前者主要目的是讓代碼格式達到一致性，後者則是規定了代碼的使用方法，最大化的減小不一樣經驗開發人員編寫代碼的質量，提升程序的可讀性、性能、穩定性及安全性。
　　在開發過程當中編程規範是一項很是重要的工做，它關係着代碼是否可以被維護，提升可維護性能夠減小團隊成員增減、功能新增、代碼變動等帶來的高成本。
　　編程規範的制定並不簡單，不一樣的人對編程規範也有不一樣的理解，特別是代碼的使用規範，它要求制定者必需要有豐富的代碼開發以及代碼優化經驗。爲了確保規範可以順利的制定，我的認爲須要以先制定後修改的方式進行，先制定是爲了避免耽誤開發工做，在開發工做開始以前制定好規範便可按規範開發，後修改，其一是在開發過程當中發現不合理的地方進行修改(口說無憑，實踐出真理)，另外是隨着團隊能力的提升，能夠總結更多的代碼使用最佳實踐。
　　文章的最後介紹了一些經常使用的規範工具，下篇文章將詳細的介紹.Net平臺下的規範工具以其使用。

　　另附上阿里巴巴定義的Java規範：　　https://github.com/alibaba/p3c/blob/master/%E9%98%BF%E9%87%8C%E5%B7%B4%E5%B7%B4Java%E5%BC%80%E5%8F%91%E6%89%8B%E5%86%8C%EF%BC%88%E8%AF%A6%E5%B0%BD%E7%89%88%EF%BC%89.pdf

參考：
　　https://docs.microsoft.com/en-us/dotnet/standard/design-guidelines/
　　https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/inside-a-program/coding-conventions
　　https://docs.microsoft.com/zh-cn/dotnet/standard/security/secure-coding-guidelines#application-code-that-is-not-a-reusable-component
　　https://orcharddojo.net/orchard-resources/Library/DevelopmentGuidelines/BestPractices/CSharp
　　https://www.codeproject.com/articles/118853/some-best-practices-for-c-application-development
　　https://weblogs.asp.net/dixin/csharp-coding-guidelines-1-fundamentals
　　https://github.com/dotnet/docfx
　　https://github.com/alibaba/p3c/blob/master/%E9%98%BF%E9%87%8C%E5%B7%B4%E5%B7%B4Java%E5%BC%80%E5%8F%91%E6%89%8B%E5%86%8C%EF%BC%88%E8%AF%A6%E5%B0%BD%E7%89%88%EF%BC%89.pdf

本文連接：http://www.javashuo.com/article/p-mmnpunlm-gn.html 

好代碼是管出來的——淺談.Net Core的代碼管理方法與落地（更新中...）