C#的程式碼規範

摘要： 程式碼是軟體開發過程的產物，程式碼的作用是通過編譯器編譯後執行，達到預期的效果(功能、穩定性、安全性等等)，而另外一個重要作用是給人閱讀。對於機器來說只要程式碼正確就能夠正確的執行程式，但是人不同，如果程式碼編寫混亂就會對程式碼閱讀造成障礙，導致程式碼無法維護，甚至會導致程式碼重構等高成本活動...

程式碼是軟體開發過程的產物，程式碼的作用是通過編譯器編譯後執行，達到預期的效果(功能、穩定性、安全性等等)，而另外一個重要作用是給人閱讀。對於機器來說只要程式碼正確就能夠正確的執行程式，但是人不同，如果程式碼編寫混亂就會對程式碼閱讀造成障礙，導致程式碼無法維護，甚至會導致程式碼重構等高成本活動，所以規範程式碼勢在必行。

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

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

.Net程式碼規範簡介

程式碼格式規範

程式碼格式規範主要的目的是統一程式碼編寫格式，避免開發人員獨特的程式碼編寫方式，以便於專案的所有開發人員能快速的閱讀其他人員開發的程式碼，程式碼格式規範主要有以下幾個方面：

注：除以下規範外，對於一個工程來說應該還有工程結構規範(也可以理解為程式碼目錄結構規範)，工程結構規範可能因專案不同而不同，但是統一規範可以提高程式碼查詢效率和開發效率(團隊新成員不會再疑惑程式碼應該放哪裡)。

命名規範

命名規範主要涉及名稱空間、型別、介面、屬性、方法、變數等相關命名，其主要規範有：

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

例：public class PersonManager {}

• 使用Camel()命名方式對引數、變數、欄位進行命名。

例：private string userName ;

禁止使用縮寫，除URL、IO等能達成共識的縮寫除外，使用縮寫可全大寫。

例：System.IO；

• 介面以I做為字首進行命名。

例：public interface I Convertor {}

• 抽象類以Abstract為字首或者以Base為字尾進行命名。

例：public abstract class Person Base {}

• 異常型別以Exception為字尾。

例：public class Custom Exception {}

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

例： 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平臺下的規範工具以其使用。