代碼是軟件開(kāi)發(fā)過(guò)程的產(chǎn)物，代碼的作用是通過(guò)編譯器編譯后運(yùn)行，達(dá)到預(yù)期的效果(功能、穩(wěn)定性、安全性等等)，而另外一個(gè)重要作用是給人閱讀。對(duì)于機(jī)器來(lái)說(shuō)只要代碼正確就能夠正確的運(yùn)行程序，但是人不同，如果代碼編寫(xiě)混亂就會(huì)對(duì)代碼閱讀造成障礙，導(dǎo)致代碼無(wú)法維護(hù)，甚至?xí)?dǎo)致代碼重構(gòu)等高成本活動(dòng)，所以規(guī)范代碼勢(shì)在必行。

　　本文從以下幾個(gè)方面介紹代碼規(guī)范以及相關(guān)工具。

• .Net代碼規(guī)范簡(jiǎn)介

• 代碼格式規(guī)范

  • 命名規(guī)范

  • 布局規(guī)范

  • 注釋規(guī)范

• 代碼使用規(guī)范

• 常用的代碼規(guī)范工具

• 小結(jié)

.Net代碼規(guī)范簡(jiǎn)介

　　文章開(kāi)始提到過(guò)代碼是給人看的，代碼規(guī)范的目的在于創(chuàng)建一個(gè)統(tǒng)一的規(guī)范來(lái)保持代碼的整潔，這樣有利于提高代碼的可維護(hù)性，但除此之外還可以將一些代碼的最佳實(shí)踐也作為規(guī)范的一部分，這樣還可以提高代碼的性能和安全性。
　　一般來(lái)說(shuō).Net的代碼規(guī)范主要有：代碼格式規(guī)范、代碼使用規(guī)范，前者保證代碼可讀性后者保證代碼執(zhí)行效率和安全性。

代碼格式規(guī)范

　　代碼格式規(guī)范主要的目的是統(tǒng)一代碼編寫(xiě)格式，避免開(kāi)發(fā)人員獨(dú)特的代碼編寫(xiě)方式，以便于項(xiàng)目的所有開(kāi)發(fā)人員能快速的閱讀其他人員開(kāi)發(fā)的代碼，代碼格式規(guī)范主要有以下幾個(gè)方面：

　　注：除以下規(guī)范外，對(duì)于一個(gè)工程來(lái)說(shuō)應(yīng)該還有工程結(jié)構(gòu)規(guī)范(也可以理解為代碼目錄結(jié)構(gòu)規(guī)范)，工程結(jié)構(gòu)規(guī)范可能因項(xiàng)目不同而不同，但是統(tǒng)一規(guī)范可以提高代碼查找效率和開(kāi)發(fā)效率(團(tuán)隊(duì)新成員不會(huì)再疑惑代碼應(yīng)該放哪里)。

命名規(guī)范

　　命名規(guī)范主要涉及命名空間、類(lèi)型、接口、屬性、方法、變量等相關(guān)命名，其主要規(guī)范有：

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

　　例：public class?PersonManager?{}

• 使用Camel()命名方式對(duì)參數(shù)、變量、字段進(jìn)行命名。

　　例：private string?userName;
　　禁止使用縮寫(xiě)，除URL、IO等能達(dá)成共識(shí)的縮寫(xiě)除外，使用縮寫(xiě)可全大寫(xiě)。
　　例：System.IO；

• 接口以I做為前綴進(jìn)行命名。

　　例：public interface?IConvertor {}

• 抽象類(lèi)以Abstract為前綴或者以Base為后綴進(jìn)行命名。

　　例：public abstract class PersonBase?{}

• 異常類(lèi)型以Exception為后綴。

　　例：public class CustomException?{}

• 在對(duì)任何東西命名時(shí)需要使用有意義的名稱(chēng)，并且保證單詞拼寫(xiě)正確以及語(yǔ)法正確，避免使用拼音(地名等通用拼音除外)。

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

布局規(guī)范

　　布局規(guī)范的目的是使代碼變得整潔，提高代碼可讀性，其主要規(guī)范有：

• 代碼縮進(jìn)為4個(gè)空格。

　　左右花括號(hào)必須獨(dú)自一行，括號(hào)內(nèi)容為空時(shí)除外：
　　例：public void WriteLog(string log)
　　　　{
　　　　　　Console.WriteLine(log);
　　　　}

　　　　public void EmptyMethod(string log) {}

• 括號(hào)的使用：

  • if/for/while/do等關(guān)鍵字后面與左括號(hào)直接需要加空格：

　　　　　　if (x == 1)

• 
  

  • 運(yùn)算符左右需要加空格：

　　　　　　a = c + b;

• 單行代碼限制120個(gè)字符，超長(zhǎng)處理方式：

  • 第二行相對(duì)第一行縮進(jìn)4個(gè)空格，從第三行開(kāi)始無(wú)需縮進(jìn)。

  • 運(yùn)算符及方法調(diào)用的“.”需要跟隨換行，但逗號(hào)不需要。

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

注釋規(guī)范

　　注釋用來(lái)對(duì)編寫(xiě)的代碼進(jìn)行說(shuō)明，包括功能說(shuō)明以及實(shí)現(xiàn)說(shuō)明，這樣可以大大的提高程序的可讀性，另外規(guī)范的注釋還可以通過(guò)工具來(lái)生成相應(yīng)的API文檔，C#的注釋規(guī)范有以下幾種：

• 類(lèi)注釋

　　例：/// <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
　　*/

代碼使用規(guī)范

　　代碼的使用規(guī)范，或者說(shuō)是代碼編寫(xiě)的最佳“實(shí)踐”(當(dāng)然優(yōu)良的格式規(guī)范也是一種最佳實(shí)踐)，它們是根據(jù)代碼的實(shí)現(xiàn)/運(yùn)行原理以及特定的應(yīng)用場(chǎng)景進(jìn)行實(shí)踐的最佳方案，這些方案的使用除了可以提高代碼的可讀行外，還可以減少程序Bug、提高程序性能及安全性，如以下幾個(gè)方面：

• 使用語(yǔ)言特性

　　this：使用this區(qū)分類(lèi)型中的屬性與變量、靜態(tài)成員，可以提高程序可讀性。
　　var：適當(dāng)?shù)氖褂胿ar可以提高開(kāi)發(fā)效率且不影響程序可讀性，如在不知道返回值具體類(lèi)型或者不需要知道類(lèi)型的時(shí)候。
　　反例：

　　

　　本例來(lái)自：https://weblogs.asp.net/dixin/csharp-coding-guidelines-4-types

• 字符串內(nèi)插(string interpolation)：字符串內(nèi)插是C#6.0的特性，使用字符串內(nèi)插可以提高程序可讀性：

　　例：

　　

• 異常

  • 當(dāng)程序出現(xiàn)與預(yù)期不符時(shí)應(yīng)該拋出異常讓程序上游處理。

  • 盡可能使用C#中內(nèi)置的異常類(lèi)型。

  • 捕獲異常必須處理。

  • 獲取指定異常而非統(tǒng)一使用Exception。

• 安全準(zhǔn)則

　　參考：https://docs.microsoft.com/zh-cn/dotnet/standard/security/secure-coding-guidelines
　　更多規(guī)范可參考：https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/inside-a-program/coding-conventions
　　代碼使用規(guī)范是一個(gè)廣泛的話題，除了以上一些通用的規(guī)范之外，還可以對(duì)OOP以及開(kāi)發(fā)框架等方面根據(jù)實(shí)際情況制定規(guī)則，使用統(tǒng)一的規(guī)范進(jìn)行開(kāi)發(fā)可以讓代碼變得更加容易管理。

常用的代碼規(guī)范工具

• Visual Studio

　　VS是非常強(qiáng)大的IDE，在眾多功能中當(dāng)然不會(huì)缺少對(duì)代碼規(guī)范的支持。

• StyleCop

　　StyleCop是一個(gè)代碼分析工具，StyleCop有兩個(gè)版本StyleCop和StyleCop Analyzers，前者適用于VS2010-VS2017所有版本，它的原理是在編譯時(shí)對(duì)代碼進(jìn)行分析，而StyleCop Analyzers僅支持VS2015+,它基于.Net的roslyn編譯框架實(shí)現(xiàn)的，它支持開(kāi)發(fā)時(shí)對(duì)代碼進(jìn)行實(shí)時(shí)分析(不再需要等編譯)。
　　StyleCop:https://github.com/StyleCop/StyleCop
　　StyleCop Analyzers:https://github.com/DotNetAnalyzers/StyleCopAnalyzers

• Resharper

　　Resharper是jetbrains公司開(kāi)發(fā)的一個(gè)VS收費(fèi)插件，它不僅包含了代碼分析，還具備了代碼生成、編譯、測(cè)試、調(diào)試等功能。
　　VS2017與Resharper的功能比較https://www.jetbrains.com/resharper/documentation/comparisonMatrix_R2018_1_vs2017.html

• EditConfig

　　EditConfig是一個(gè)跨編輯器/IDE的代碼風(fēng)格一致性維護(hù)工具(協(xié)議/插件)，現(xiàn)在VS2017已經(jīng)支持EditConfig

• DocFx

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

小結(jié)

　　本文主要介紹了C#中的編程規(guī)范，并將規(guī)范分為了兩個(gè)類(lèi)型，分別是格式規(guī)范和使用規(guī)范，前者主要目的是讓代碼格式達(dá)到一致性，后者則是規(guī)定了代碼的使用方法，最大化的減少不同經(jīng)驗(yàn)開(kāi)發(fā)人員編寫(xiě)代碼的質(zhì)量，提高程序的可讀性、性能、穩(wěn)定性及安全性。
　　在開(kāi)發(fā)過(guò)程中編程規(guī)范是一項(xiàng)非常重要的工作，它關(guān)系著代碼是否能夠被維護(hù)，提高可維護(hù)性可以減少團(tuán)隊(duì)成員增減、功能新增、代碼變更等帶來(lái)的高成本。
　　編程規(guī)范的制定并不簡(jiǎn)單，不同的人對(duì)編程規(guī)范也有不同的理解，特別是代碼的使用規(guī)范，它要求制定者必須要有豐富的代碼開(kāi)發(fā)以及代碼優(yōu)化經(jīng)驗(yàn)。為了確保規(guī)范能夠順利的制定，個(gè)人認(rèn)為需要以先制定后修改的方式進(jìn)行，先制定是為了不耽誤開(kāi)發(fā)工作，在開(kāi)發(fā)工作開(kāi)始之前制定好規(guī)范即可按規(guī)范開(kāi)發(fā)，后修改，其一是在開(kāi)發(fā)過(guò)程中發(fā)現(xiàn)不合理的地方進(jìn)行修改(口說(shuō)無(wú)憑，實(shí)踐出真理)，另外是隨著團(tuán)隊(duì)能力的提高，可以總結(jié)更多的代碼使用最佳實(shí)踐。
　　文章的最后介紹了一些常用的規(guī)范工具，下篇文章將詳細(xì)的介紹.Net平臺(tái)下的規(guī)范工具以其使用。

　　另附上阿里巴巴定義的Java規(guī)范：　　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

相關(guān)文章：

• 好代碼是管出來(lái)的——使用Git來(lái)管理源代碼

• 好代碼是管出來(lái)的——Git的分支工作流與Pull Request

• 好代碼是管出來(lái)的——使用GitHub
  

原文地址：https://www.cnblogs.com/selimsong/p/9160928.html?

.NET社區(qū)新聞，深度好文，歡迎訪問(wèn)公眾號(hào)文章匯總 http://www.csharpkit.com

總結(jié)

以上是生活随笔為你收集整理的好代码是管出来的——C#的代码规范的全部?jī)?nèi)容，希望文章能夠幫你解決所遇到的問(wèn)題。

如果覺(jué)得生活随笔網(wǎng)站內(nèi)容還不錯(cuò)，歡迎將生活随笔推薦給好友。