.Net Core 編碼規範 概述 規範制定原則 方便代碼的交流和維護。 不影響編碼的效率,不與大眾習慣衝突。 使代碼更美觀、閱讀更方便。 使代碼的邏輯更清晰、更易於理解。 術語定義 Pascal 大小寫 將標識符的首字母和後面連接的每個單詞的首字母都大寫。可以對三字元或更多字元的標識符使用Pasc ...
.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 + "\n");
- 語句中的表達式之間用空格隔開。如:
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
其他
表達式
- 避免在表達式中用賦值語句
- 避免對浮點類型做等於或不等於判斷
類型轉換
- 儘量避免強制類型轉換。
- 如果不得不做類型轉換,儘量用顯式方式。