當(dāng)前位置：首頁 > 编程语言 > C# >内容正文

C#

好代码是管出来的——C#的代码规范

發(fā)布時(shí)間：2023/12/4 C# 37 豆豆

生活随笔收集整理的這篇文章主要介紹了好代码是管出来的——C#的代码规范小編覺得挺不錯(cuò)的,現(xiàn)在分享給大家,幫大家做個(gè)參考.

代碼是軟件開發(fā)過程的產(chǎn)物，代碼的作用是通過編譯器編譯后運(yùn)行，達(dá)到預(yù)期的效果(功能、穩(wěn)定性、安全性等等)，而另外一個(gè)重要作用是給人閱讀。對(duì)于機(jī)器來說只要代碼正確就能夠正確的運(yùn)行程序，但是人不同，如果代碼編寫混亂就會(huì)對(duì)代碼閱讀造成障礙，導(dǎo)致代碼無法維護(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)介

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

代碼格式規(guī)范

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

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

命名規(guī)范

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

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

　　例：public class?PersonManager?{}

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

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

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

　　例：public interface?IConvertor {}

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

　　例：public abstract class PersonBase?{}

異常類型以Exception為后綴。

　　例：public class CustomException?{}

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

　　例： 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è)字符，超長處理方式：
- 第二行相對(duì)第一行縮進(jìn)4個(gè)空格，從第三行開始無需縮進(jìn)。
- 運(yùn)算符及方法調(diào)用的“.”需要跟隨換行，但逗號(hào)不需要。

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

注釋規(guī)范

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

類注釋

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

使用語言特性

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

　　本例來自：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)置的異常類型。
- 捕獲異常必須處理。
- 獲取指定異常而非統(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以及開發(fā)框架等方面根據(jù)實(shí)際情況制定規(guī)則，使用統(tǒng)一的規(guī)范進(jìn)行開發(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)的，它支持開發(fā)時(shí)對(duì)代碼進(jìn)行實(shí)時(shí)分析(不再需要等編譯)。
　　StyleCop:https://github.com/StyleCop/StyleCop
　　StyleCop Analyzers:https://github.com/DotNetAnalyzers/StyleCopAnalyzers

Resharper

　　Resharper是jetbrains公司開發(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è)類型，分別是格式規(guī)范和使用規(guī)范，前者主要目的是讓代碼格式達(dá)到一致性，后者則是規(guī)定了代碼的使用方法，最大化的減少不同經(jīng)驗(yàn)開發(fā)人員編寫代碼的質(zhì)量，提高程序的可讀性、性能、穩(wěn)定性及安全性。
　　在開發(fā)過程中編程規(guī)范是一項(xiàng)非常重要的工作，它關(guān)系著代碼是否能夠被維護(hù)，提高可維護(hù)性可以減少團(tuán)隊(duì)成員增減、功能新增、代碼變更等帶來的高成本。
　　編程規(guī)范的制定并不簡(jiǎn)單，不同的人對(duì)編程規(guī)范也有不同的理解，特別是代碼的使用規(guī)范，它要求制定者必須要有豐富的代碼開發(fā)以及代碼優(yōu)化經(jīng)驗(yàn)。為了確保規(guī)范能夠順利的制定，個(gè)人認(rèn)為需要以先制定后修改的方式進(jìn)行，先制定是為了不耽誤開發(fā)工作，在開發(fā)工作開始之前制定好規(guī)范即可按規(guī)范開發(fā)，后修改，其一是在開發(fā)過程中發(fā)現(xiàn)不合理的地方進(jìn)行修改(口說無憑，實(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)文章：

好代碼是管出來的——使用Git來管理源代碼
好代碼是管出來的——Git的分支工作流與Pull Request
好代碼是管出來的——使用GitHub

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

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

總結(jié)

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

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

代码

上一篇：要用Identity Server 4
下一篇： .NET Core微服务之基于Ident