.Net Core 編碼規範

.Net Core 編碼規範

標籤： 未分類

概述

規範制定原則

• 方便程式碼的交流和維護。
• 不影響編碼的效率，不與大眾習慣衝突。
• 使程式碼更美觀、閱讀更方便。
• 使程式碼的邏輯更清晰、更易於理解。

術語定義

Pascal 大小寫

將識別符號的首字母和後面連線的每個單詞的首字母都大寫。可以對三字元或更多字元的識別符號使用Pascal 大小寫。例：

BackColor

Camel 大小寫

識別符號的首字母小寫，而每個後面連線的單詞的首字母都大寫。例：

backColor

匈牙利命名法

匈牙利命名法是一名匈牙利程式設計師發明的，而且他在微軟工作了多年。此命名法就是通過微軟的各種產品和文件傳出來的。多數有經驗的程式設計師，不管他們用的是哪門兒語言，都或多或少在使用它。

這種命名法的基本原則是：

變數名＝屬性＋型別＋物件描述

即一個變數名是由三部分資訊組成，這樣，程式設計師很容易理解變數的型別、用途，而且便於記憶。

下邊是一些推薦使用的規則例子，你可以挑選使用，也可以根據個人喜好作些修改再用之。

• 屬性部分：
• 全域性變數： g_
• 常量 ： c_

• 類成員變數： m_

• 型別部分：
• 指標： p
• 控制程式碼： h
• 布林型： b
• 浮點型： f

• 無符號： u

• 描述部分：
• 初始化： Init
• 臨時變數： Tmp
• 目的物件： Dst
• 源物件： Src

• 視窗： Wnd

下邊舉例說明：

• hwnd： h表示控制程式碼，wnd表示視窗，合起來為“視窗控制程式碼”。
• m_bFlag： m表示成員變數，b表示布林，合起來為：“某個類的成員變數，布林型，是一個狀態標誌”。

程式碼外觀

列寬

程式碼列寬控制在120字元左右。

換行

當表示式超出或即將超出規定的列寬，遵循以下規則進行換行

• 在逗號後換行。
• 在操作符前換行。
• 規則1優先於規則2。

當以上規則會導致程式碼混亂的時候自己採取更靈活的換行規則。

縮排

縮排應該是每行一個Tab(4個空格)，不要在程式碼中使用Tab字元。

Visual Studio 設定：工具->選項->文字編輯器->C#->製表符->插入空格，製表符大小=4，縮排大小=4

空行

空行是為了將邏輯上相關聯的程式碼分塊，以便提高程式碼的可閱讀性。

在以下情況下使用兩個空行

• 介面和類的定義之間。
• 列舉和類的定義之間。
• 類與類的定義之間。

在以下情況下使用一個空行

• 方法與方法、屬性與屬性之間。
• 方法中變數宣告與語句之間。
• 方法與方法之間。
• 方法中不同的邏輯塊之間。
• 方法中的返回語句與其他的語句之間。
• 屬性與方法、屬性與欄位、方法與欄位之間。
• 註釋與它註釋的語句間不空行，但與其他的語句間空一行。

空格

在以下情況中要使用到空格

• 關鍵字和左括符 “(” 應該用空格隔開。如：

while (true)

注意在方法名和左括符 “(” 之間不要使用空格，這樣有助於辨認程式碼中的方法呼叫與關鍵字。

• 多個引數用逗號隔開，每個逗號後都應加一個空格。
• 除了 . 之外，所有的二元操作符都應用空格與它們的運算元隔開。一元操作符、++及–與運算元間不需要空格。如：

a += c + d;
a = (a + b)/(c*d);

while (d++ == s++)
{
    n++;
}

PrintSize("size is " + size + "
");

• 語句中的表示式之間用空格隔開。如：

for (expr1; expr2; expr3)

括號 – ()

• 左括號“(”不要緊靠關鍵字，中間用一個空格隔開。
• 左括號“(”與方法名之間不要新增任何空格。
• 沒有必要的話不要在返回語句中使用()。

花括號 – {}

• 左花括號 “{” 放於關鍵字或方法名的下一行並與之對齊。如：

if (condition)
{
}

public int Add(int x, int y)
{
}

• 左花括號 “{” 要與相應的右花括號 “}”對齊。
• 通常情況下左花括號 “{”單獨成行，不與任何語句並列一行。
• if、while、do語句後一定要使用{}，即使{}號中為空或只有一條語句。如：

if (somevalue == 1)
{
    somevalue = 2;
}

• 右花括號 “}” 後建議加一個註釋以便於方便的找到與之相應的 {。如:

while(1)
{
    if(valid)
    {
    } // if valid
    else
    {
    } // not valid
} // end forever

程式註釋

註釋概述

• 修改程式碼時，總是使程式碼周圍的註釋保持最新。
• 在每個例程的開始，提供標準的註釋樣本以指示例程的用途、假設和限制很有幫助。註釋樣本應該是解釋它為什麼存在和可以做什麼的簡短介紹.
• 避免在程式碼行的末尾新增註釋；行尾註釋使程式碼更難閱讀。不過在批註變數宣告時，行尾註釋是合適的；在這種情況下，將所有行尾註釋在公共製表位處對齊。
• 避免雜亂的註釋，如一整行星號。而是應該使用空白將註釋同程式碼分開。
• 避免在塊註釋的周圍加上印刷框。這樣看起來可能很漂亮，但是難於維護。
• 在部署釋出之前，移除所有臨時或無關的註釋，以避免在日後的維護工作中產生混亂。
• 如果需要用註釋來解釋複雜的程式碼節，請檢查此程式碼以確定是否應該重寫它。盡一切可能不註釋難以理解的程式碼，而應該重寫它。儘管一般不應該為了使程式碼更簡單以便於人們使用而犧牲效能，但必須保持效能和可維護性之間的平衡。
• 在編寫程式碼時就註釋，因為以後很可能沒有時間這樣做。另外，如果有機會複查已編寫的程式碼，在今天看來很明顯的東西六週以後或許就不明顯了。
• 避免多餘的或不適當的註釋，不應包含個人情緒內容，如幽默的不主要的備註。
• 在編寫註釋時使用完整的句子。註釋應該闡明程式碼，而不應該增加多義性。
• 使用註釋來解釋程式碼的意圖。它們不應作為程式碼的聯機翻譯。
• 註釋程式碼中不十分明顯的內容。
• 為了防止問題反覆出現，對錯誤修復和解決方法程式碼總是使用註釋。
• 對由迴圈和邏輯分支組成的程式碼使用註釋。這些是幫助原始碼讀者的主要方面。
• 在整個應用程式中，使用具有一致的標點和結構的統一樣式來構造註釋。
• 用空白將註釋同註釋分隔符分開。在沒有顏色提示的情況下檢視註釋時，這樣做會使註釋很明顯且容易被找到。
• 程式碼修改變更記錄不應使用註釋標明修改日期和修改人，註釋應只針對程式碼不記錄版本，程式碼版本應該使用程式碼版本系統進行管理
• 為了使層次清晰，在閉合的右花括號後註釋該閉合所對應的起點。

namespace SCB.Framework.Web 
{
} // namespace SCB.Framework.Web

文件型註釋

該類註釋採用.Net已定義好的Xml標籤來標記，在宣告介面、類、方法、屬性、欄位都應該使用該類註釋，以便程式碼完成後直接生成程式碼文件，讓別人更好的瞭解程式碼的實現和介面。如

/// <summary> MyMethod is a method in the MyClass class.
/// <para> Here`s how you could make a second paragraph in a description.
/// <see cref="System.Console.WriteLine"/> 
/// for information about output statements.
/// </para>
/// <seealso cref="MyClass.Main"/>
/// </summary>
public static void MyMethod(int Int1)
{
}

註釋標籤的使用請參考:http://msdn.microsoft.com/zh-cn/library/5ast78ax.aspx

類c註釋

該類註釋用於

• 複雜程式邏輯說明與技術事項

用法

/*
動態路由演算法使用Round-robin演算法，原理是...
*/

單行註釋

該類註釋用於

• 方法內的程式碼註釋。如變數的宣告、程式碼或程式碼段的解釋。例：

//
// 註釋語句
// 
private int number;

或

// 註釋語句
private int number;

• 方法內變數的宣告或花括號後的註釋, 例：

if (1 == 1) // always true
{
    statement; 
} // always true

宣告

每行宣告數

一行只建議作一個宣告，並按字母順序排列。如：

int level; // 推薦
int size; // 推薦
int x, y; // 不推薦

初始化

建議在變數宣告時就對其做初始化。

位置

變數建議置於塊的開始處，不要總是在第一次使用它們的地方做宣告。如：

void MyMethod()
{
    int int1 = 0;

    if (condition)
    {
        int int2 = 0;
        ...
    }
}

例外情況

for (int i = 0; i < maxLoops; i++)
{
    ...
}

應避免不同層次間的變數重名，如：

int count;
...

void MyMethod()
{
    if (condition)
    {
        int count = 0; // 避免
        ...
    }
    ...
}

類和介面的宣告

• 在方法名與其後的左括號間沒有任何空格。
• 左花括號 “{” 出現在宣告的下行並與之對齊，單獨成行。
• 方法間用一個空行隔開。

欄位的宣告

不要使用是 public 或 protected 的例項欄位。如果避免將欄位直接公開給開發人員，可以更輕鬆地對類進行版本控制，原因是在維護二進位制相容性時欄位不能被更改為屬性。考慮為欄位提供 get 和set 屬性訪問器，而不是使它們成為公共的。 get 和 set 屬性訪問器中可執行程式碼的存在使得可以進行後續改進，如在使用屬性或者得到屬性更改通知時根據需要建立物件。下面的程式碼示例闡釋帶有 get 和 set 屬性訪問器的私有例項欄位的正確使用。例：

public class Control: Component
{
    private int handle;

    public int Handle
    {
        get
        {
            return handle; 
        }
    }
}

命名規範

命名概述

名稱應該說明“什麼”而不是“如何”。通過避免使用公開基礎實現（它們會發生改變）的名稱，可以保留簡化複雜性的抽象層。例如，可以使用 GetNextStudent()，而不是 GetNextArrayElement()。

命名原則是：

選擇正確名稱時的困難可能表明需要進一步分析或定義項的目的。使名稱足夠長以便有一定的意義，並且足夠短以避免冗長。唯一名稱在程式設計上僅用於將各項區分開。表現力強的名稱是為了幫助人們閱讀；因此，提供人們可以理解的名稱是有意義的。不過，請確保選擇的名稱符合適用語言的規則和標準。

以下幾點是推薦的命名方法：

• 避免容易被主觀解釋的難懂的名稱，如方面名 AnalyzeThis()，或者屬性名 xxK8。這樣的名稱會導致多義性。
• 在類屬性的名稱中包含類名是多餘的，如 Book.BookTitle。而是應該使用 Book.Title。
• 只要合適，在變數名的末尾或開頭加計算限定符（Avg、Sum、Min、Max、Index）。
• 在變數名中使用互補對，如 min/max、begin/end 和 open/close。
• 布林變數名應該包含 Is，這意味著 Yes/No 或 True/False 值，如 fileIsFound。
• 在命名狀態變數時，避免使用諸如 Flag 的術語。狀態變數不同於布林變數的地方是它可以具有兩個以上的可能值。不是使用 documentFlag，而是使用更具描述性的名稱，如 documentFormatType。
• 即使對於可能僅出現在幾個程式碼行中的生存期很短的變數，仍然使用有意義的名稱。僅對於短迴圈索引使用單字母變數名，如 i 或 j。 可能的情況下，儘量不要使用原義數字（幻數）或原義字串，如
  for (int i = 1; i < 7; i++)。而是使用命名常數，如 for (int i = 1; i < NUM_DAYS_IN_WEEK; i++) 以便於維護和理解。

大小寫規則

大寫

• 組織名縮寫使用大寫
• 兩個或者更少字母組成的識別符號使用大寫。例：

System.IO
System.Web.UI
SCB.Framework.UI

下表彙總了大寫規則，並提供了不同型別的識別符號的示例。

識別符號	大小寫	示例
類	Pascal	AppDomain
列舉型別	Pascal	ErrorLevel
列舉值	Pascal	FatalError
事件	Pascal	ValueChange
異常類	Pascal	WebException 注意: 總是以 Exception 字尾結尾。
只讀的靜態欄位	Pascal	RedValue
介面	Pascal	IDisposable 注意: 總是以 I 字首開始。
方法	Pascal	ToString
名稱空間	Pascal	System.Drawing
屬性	Pascal	BackColor
公共例項欄位	Pascal	RedValue 注意: 應優先使用屬性。
受保護的例項欄位	Camel	redValue 注意: 應優先使用屬性。
私有的例項欄位	Camel	redValue
引數	Camel	typeName
方法內的變數	Camel	backColor

縮寫

為了避免混淆和保證跨語言互動操作，請遵循有關區縮寫的使用的下列規則：

• 不要將縮寫或縮略形式用作識別符號名稱的組成部分。例如，使用 GetWindow，而不要使用 GetWin。
• 不要使用計算機領域中未被普遍接受的縮寫。
• 在適當的時候，使用眾所周知的縮寫替換冗長的片語名稱。例如，用 UI 作為 User Interface 縮
  寫，用 OLAP 作為 On-line Analytical Processing 的縮寫。
• 在使用縮寫時，對於超過兩個字元長度的縮寫請使用 Pascal 大小寫或 Camel 大小寫。例如使用 HtmlButton 或 HTMLButton；但是，應當大寫僅有兩個字元的縮寫，如：System.IO，而不是 System.Io。
• 不要在識別符號或引數名稱中使用縮寫。如果必須使用縮寫，對於由多於兩個字元所組成的縮寫請使用Camel 大小寫。

名稱空間

• 命名名稱空間時的一般性規則是使用公司名稱，後跟技術名稱和可選的功能與設計，如：

CompanyName.TechnologyName[.Feature][.Design]

例如：

namespace SCB.SupplierChain  // 賽酷比公司的供應鏈系統
namespace SCB.SupplierChain.DataRules // 賽酷比公司的供應鏈系統的業務規則模組

• 名稱空間使用Pascal大小寫。
• TechnologyName 指的是該專案的英文縮寫或軟體名。
• 名稱空間和類不能使用同樣的名字。例如，有一個類被命名為Debug後，就不要再使用Debug作為一個名稱空間名。

類

• 使用 Pascal 大小寫。
• 用名詞或名詞短語命名類。
• 使用全稱避免縮寫，除非縮寫已是一種公認的約定，如URL、HTML
• 不要使用型別字首，如在類名稱上對類使用 C 字首。例如，使用類名稱 FileStream，而不是
  CFileStream。
• 不要使用下劃線字元 (_)。
• 有時候需要提供以字母 I 開始的類名稱，雖然該類不是介面。只要 I 是作為類名稱組成部分的整個單詞的第一個字母，這便是適當的。例如，類名稱 IdentityStore 是適當的。在適當的地方，使用複合單詞命名派生的類。派生類名稱的第二個部分應當是基類的名稱。例如，ApplicationException 對於從名為 Exception 的類派生的類是適當的名稱，原因ApplicationException 是一種Exception。請在應用該規則時進行合理的判斷。例如，Button 對於從 Control 派生的類是適當的名稱。儘管按鈕是一種控制元件，但是將 Control 作為類名稱的一部分將使名稱不必要地加長。

public class FileStream
public class Button
public class String

介面

• 用名詞或名詞短語，或者描述行為的形容詞命名介面。例：
  • 介面名稱 IComponent 使用描述性名詞
  • 介面名稱 ICustomAttributeProvider 使用名詞短語
  • 介面名稱 IPersistable 使用形容詞。
• 使用 Pascal 大小寫。
• 少用縮寫。
• 給介面名稱加上字母 I 字首，以指示該型別為介面。在定義類/介面對（其中類是介面的標準實現）時使用相似的名稱。兩個名稱的區別應該只是介面名稱上有字母 I 字首。
• 不要使用下劃線字元 (_)。

 public interface IServiceProvider
 public interface IFormatable

以下程式碼示例闡釋如何定義 IComponent 介面及其標準實現 Component 類。

public interface IComponent
{
    // Implementation code goes here.
}

public class Component: IComponent 
{
    // Implementation code goes here.
}

屬性類 (Attribute)

應該總是將字尾 Attribute 新增到自定義屬性類。例：

public class ObsoleteAttribute
{
}

列舉 (Enum)

列舉 (Enum) 值型別從 Enum 類繼承。

• 對於 Enum 型別和值名稱使用 Pascal 大小寫。
• 少用縮寫。
• 不要在 Enum 型別名稱上使用 Enum 字尾。
• 對大多數 Enum 型別使用單數名稱，但是對作為位域的 Enum 型別使用複數名稱。
• 總是將 FlagsAttribute 新增到位域 Enum 型別。

引數

• 使用描述性引數名稱。引數名稱應當具有足夠的描述性，以便引數的名稱及其型別可用於在大多數情況下確定它的含義。
• 對引數名稱使用 Camel 大小寫。
• 使用描述引數的含義的名稱，而不要使用描述引數的型別的名稱。開發工具將提供有關引數的型別的有意義的資訊。因此，通過描述意義，可以更好地使用引數的名稱。
• 不要給引數名稱加匈牙利語型別表示法的字首，僅在適合使用它們的地方使用它們。
• 不要使用保留的引數。保留的引數是專用引數，如果需要，可以在未來的版本中公開它們。相反，如果在類庫的未來版本中需要更多的資料，請為方法新增新的過載。

Type GetType(string typeName)
string Format(string format, object args)

方法

• 使用動詞或動詞短語命名方法。
• 使用 Pascal 大小寫。

RemoveAll()
GetCharArray()
Invoke()

屬性 (property)

• 使用名詞或名詞短語命名屬性。
• 使用 Pascal 大小寫。
• 考慮用與屬性的基礎型別相同的名稱建立屬性。例如，如果宣告名為 Color 的屬性，則屬
  性的型別同樣應該是 Color。

public class SampleClass
{
    public Color BackColor 
    {
        // Code for Get and Set accessors goes here.
    }
}

以下程式碼示例闡釋提供其名稱與型別相同的屬性。

public enum Color 
{
    // Insert code for Enum here.
}

public class Control
{
    public Color Color 
    { 
        get
        {
            // Insert code here.
        }

        set
        {
            // Insert code here.
        } 
    }
}

事件

• 對事件處理程式名稱使用 EventHandler 字尾。
• 指定兩個名為 sender 和 e 的引數。sender 參數列示引發事件的物件。sender 引數始
  終是 object 型別的，即使在可以使用更為特定的型別時也如此。與事件相關聯的狀態封裝
  在名為 e 的事件類的例項中。對 e 引數型別使用適當而特定的事件類。
• 用 EventArgs 字尾命名事件引數類。
• 考慮用動詞命名事件。
• 使用動名詞（動詞的“ing”形式）建立表示事件前的概念的事件名稱，用過去式表示事
  件後。例如，可以取消的 Close 事件應當具有 Closing 事件和 Closed 事件。不要使用
  BeforeXxx/AfterXxx 命名模式。
• 不要在型別的事件宣告上使用字首或者字尾。例如，使用 Close，而不要使用 OnClose。
• 通常情況下，對於可以在派生類中重寫的事件，應在型別上提供一個受保護的方法（稱為
  OnXxx）。此方法只應具有事件引數 e，因為傳送方總是型別的例項。

public delegate void MouseEventHandler(object sender, MouseEventArgs e);

public class MouseEventArgs : EventArgs 
{
    int x;
    int y;

    public MouseEventArgs(int x, int y) 
    {
        this.x = x;
        this.y = y; 
    }

    public int X
    {
        get
        {
            return x;
        }
    }

    public int Y
    {
        get
        {
            return y;
        }
    }
}

常量 (const)

所有單詞大寫，多個單詞之間用 “_” 隔開。 如：

public const string PAGE_TITLE = "Welcome";

欄位

• private、protected 使用 Camel 大小寫。
• public 使用 Pascal 大小寫。
• 拼寫出欄位名稱中使用的所有單詞。僅在開發人員一般都能理解時使用縮寫。

class SampleClass
{
    string url;
    string destinationUrl;
}

• 不要對欄位名使用匈牙利語表示法。好的名稱描述語義，而非型別。
• 不要對欄位名或靜態欄位名應用字首。具體說來，不要對欄位名稱應用字首來區分靜態和非靜態欄位。例如，應用 g_ 或 s_ 字首是不正確的。
• 對預定義物件例項使用公共靜態只讀欄位。如果存在物件的預定義例項，則將它們宣告為
  物件本身的公共靜態只讀欄位。使用 Pascal 大小寫，原因是欄位是公共的。

public struct Color
{
    public static readonly Color Red = new Color(0x0000FF);

    public Color(int rgb)
    {
        // Insert code here.
    }

    public Color(byte r, byte g, byte b)
    {
        // Insert code here.
    }

    public byte RedValue 
    {
        get
        {
            return Color;
        }
    }
}

靜態欄位

• 使用名詞、名詞短語或者名詞的縮寫命名靜態欄位。
• 使用 Pascal 大小寫。
• 建議儘可能使用靜態屬性而不是公共靜態欄位。

集合

集合是一組組合在一起的類似的型別化物件，如雜湊表、查詢、堆疊、字典和列表，集合的命名建議用複數。

措詞

避免使用與常用的 .NET 框架名稱空間重複的類名稱。例如，不要將以下任何名稱用作類名稱：System、Collections、Forms 或 UI。有關 .NET 框架名稱空間的列表，請參閱類庫。

另外，避免使用與C#語言關鍵字衝突的識別符號。

語句

每行一個語句

每行最多包含一個語句。如：

a++; // 推薦
b--; // 推薦
a++; b--; // 不推薦

複合語句

複合語句是指包含”父語句{子語句;子語句;}”的語句，使用複合語句應遵循以下幾點

• 子語句要縮排。
• 左花括號“{” 在複合語句父語句的下一行並與之對齊，單獨成行。
• 即使只有一條子語句要不要省略花括號“ {}”。 如：

while(d += s++)
{
    n++;
}

return 語句

return語句中不使用括號，除非它能使返回值更加清晰。如：

return;
return myDisk.size();
return (size ? size : defaultSize);

if、 if-else、if else-if 語句

if、 if-else、if else-if 語句使用格式

if (condition)
{
    statements;
}

if (condition)
{
    statements;
}
else
{
    statements;
}

if (condition)
{
    statements;
}
else if (condition)
{
    statements;
}
else
{
    statements;
}

for、foreach 語句

for 語句使用格式

for (initialization; condition; update)
{
    statements;
}

空的 for 語句（所有的操作都在initialization、condition 或 update中實現）使用格式

for (initialization; condition; update); // update user id

foreach 語句使用格式

foreach (object obj in array)
{
    statements;
}

注意

• 在迴圈過程中不要修改迴圈計數器。
• 對每個空迴圈體給出確認性註釋。

while 語句

while 語句使用格式

while (condition)
{
    statements;
}

空的 while 語句使用格式

while (condition);

do – while 語句

do – while 語句使用格式

do
{
    statements;
} while (condition);

switch – case 語句

switch – case語句使用格式

switch (condition)
{
    case 1:
        statements;
        break;

    case 2:
        statements;
        break;

    default:
        statements;
        break;
}

注意：

• 語句switch中的每個case各佔一行。
• 為所有switch語句提供default分支。
• 所有的非空 case 語句必須用 break; 語句結束。

try – catch 語句

try – catch語句使用格式

try
{
    statements;
}
catch (ExceptionClass e)
{
    statements;
}
finally
{
    statements;
}

using 塊語句

using 塊語句使用格式

using (object)
{
    statements;
}

控制元件命名規則

命名方法

控制元件名簡寫+英文描述，英文描述首字母大寫

主要控制元件名簡寫對照表

• 控制元件名 => 簡寫
• Label => lbl
• TextBox => txt
• Button => btn
• LinkButton => lnkbtn
• ImageButton => imgbtn
• DropDownList => ddl
• ListBox => lst
• DataGrid => dg
• DataList => dl
• CheckBox => chk
• CheckBoxList => chkls
• RadioButton => rdo
• RadioButtonList => rdolt
• Image => img
• Panel => pnl
• Calender => cld
• AdRotator => ar
• Table => tbl
• RequiredFieldValidator => rfv
• CompareValidator => cv
• RangeValidator => rv
• RegularExpressionValidator => rev
• ValidatorSummary => vs
• CrystalReportViewer => rptvew

其他

表示式

• 避免在表示式中用賦值語句
• 避免對浮點型別做等於或不等於判斷

型別轉換

• 儘量避免強制型別轉換。
• 如果不得不做型別轉換，儘量用顯式方式。