C#程式設計規範
大家好像都一個版本此處轉
http://tech.ddvip.com/2008-11/122794615696216.html
http://tech.ddvip.com/2008-11/122794629896218.html
1
本規範為一套編寫高效可靠的 C# 程式碼的標準、約定和指南。它以安全可靠的軟體工程原則為基礎,使程式碼易於理解、維護和增強,提高生產效率。同時,將帶來更大的一致性,使軟體開發團隊的效率明顯提高。
2 2. 適用範圍
本規範適用於公司所有的C# 原始碼,為詳細設計,程式碼編寫和程式碼稽核提供參考和依據。
3 3. 文體
本規範中的建議分為四種:要,建議,避免,不要
,表示需要遵循的級別。文件中會以粗體表示。對於應遵循的規範,前面會以“Ö”
來表示,對不好的做法前面會以“´”
要 :描述必須遵循的規範。例如:
Ö 異常類要 以“Exception” 做為字尾;
建議 :描述在一般情況下應該遵循的規範,但如果完全理解規範背後的道理,並有很好的理由不遵循它時,也不畏懼打破常規。例如:
Ö 強制型別轉換時,在型別和變數之間建議 加一空格。
不要 :描述一些幾乎絕對絕不應該違反的規範。例如:
´ 每個函式有效程式碼(不包括註釋和空行)長度不要 超過50 行。
避免 :與建議 相對,一般情況下應該遵循,但有很好的理由時也可以打破。例如:
´
對一些規範內容一併提供了示例程式碼。
4 4. 程式碼組織與風格
Ö 要 使一個Tab 為4 個空格長。
6 4.2. 縮排
Ö 要 使一個程式碼塊內的程式碼都統一縮排一個Tab 長度。
7 4.3. 空行
Ö 建議 適當的增加空行,來增加程式碼的可讀性。
Ö 在在類,介面以及彼此之間要 有兩行空行:
Ö 在下列情況之間要 有一行空行:
方法之間;
區域性變數和它後邊的語句之間;
方法內的功能邏輯部分之間;
8 4.4. 函式長度
´ 每個函式有效程式碼(不包括註釋和空行)長度不要 超過50 行。
Ö 開括號“{” 要 放在塊的所有者的下一行,單起一行;
Ö 閉括號“}” 要 單獨放在程式碼塊的最後一行,單起一行。
´ 每行程式碼和註釋不要 超過70 個字元或螢幕的寬度,如超過則應換行,換行後的程式碼應該縮排一個Tab 。
´ 括號和它裡面的字元之間不要 出現空格。括號應該和它前邊的關鍵詞留有空格,如:while (true) {};
´ 但是方法名和左括號之間不要 有空格。
Ö 引數之間的逗號後要 加一空格。如:method1(int i1, int i2)
Ö for 語句裡的表示式之間要 加一空格。如:for (expr1; expr2; expr3)
Ö 二元操作符和運算元之間要 用空格隔開。如:i + c;
Ö 強制型別轉換時,在型別和變數之間要 加一空格。如:(int) i ;
12 5. 註釋
Ö 註釋應該增加程式碼的清晰度;
Ö 保持註釋的簡潔,不是任何程式碼都需要註釋的,過多的註釋反而會影響程式碼的可讀性。
´ 註釋不要 包括其他的特殊字元。
Ö 建議 先寫註釋,後寫程式碼,註釋和程式碼一起完成
Ö 如果語句塊(比如迴圈和條件分枝的程式碼塊)程式碼太長,巢狀太多,則在其結束“ }” 要 加上註釋,標誌對應的開始語句。如果分支條件邏輯比較複雜,也要 加上註釋。
Ö 在VS2005 環境中通過配置工程編譯時輸出XML 文件檔案可以檢查註釋的完整情況,如果註釋不完整會報告編譯警告;
5.2.1 . 塊註釋
Ö 主要用來描述檔案,類,方法,演算法等,放在所描述物件的前邊。具體格式以IDE 編輯器輸入“///” 自動生成的格式為準,另外再附加我們自定義的格式,如下所列:
/// <Remark> 作者,建立日期,修改日期</ Remark >
對類和介面的註釋必須加上上述標記,對方法可以視情況考慮
5.2.2 . 行註釋
Ö 主要用在方法內部,對程式碼,變數,流程等進行說明。整個註釋佔據一行。
5.2.3 . 尾隨註釋
Ö 與行註釋功能相似,放在程式碼的同行,但是要與程式碼之間有足夠的空間,便於分清。例:
int m = 4 ; / / 註釋
Ö 如果一個程式塊內有多個尾隨註釋,每個註釋的縮排要 保持一致。
專案 |
註釋哪些部分 |
引數 |
引數用來做什麼 任何約束或前提條件 |
欄位/ 屬性 |
欄位描述 |
類 |
類的目的 已知的問題 類的開發/ 維護歷史 |
介面 |
目的 它應如何被使用以及如何不被使用 |
區域性變數 |
用處/ 目的 |
成員函式註釋 |
成員函式做什麼以及它為什麼做這個 哪些引數必須傳遞給一個成員函式 成員函式返回什麼 已知的問題 任何由某個成員函式丟擲的異常 成員函式是如何改變物件的 包含任何修改程式碼的歷史 如何在適當情況下呼叫成員函式的例子適用的前提條件和後置條件 |
成員函式內部註釋 |
控制結構 程式碼做了些什麼以及為什麼這樣做 區域性變數 難或複雜的程式碼 處理順序 |
Ö 新增程式碼行的前後要 有註釋行說明,對具體格式不作要求,但必須包含作者,新增時間,新增目的。在新增程式碼的最後必須加上結束標誌;
Ö 刪除程式碼行的前後要 用註釋行說明,刪除程式碼用註釋原有程式碼的方法。註釋方法和內容同新增;刪除的程式碼行建議 用#region XXX #endregion 程式碼段摺疊,保持程式碼檔案乾淨整潔
Ö 修改程式碼行建議 以刪除程式碼行後再新增程式碼行的方式進行(針對別人的程式碼進行修改時,必須標明,對於自己的程式碼進行修改時,酌情進行)。註釋方法和內容同新增;
17 6. 命名
Ö 要 使用可以準確說明變數/ 欄位/ 類的完整的英文描述符,如firstName 。對一些作用顯而易見的變數可以採用簡單的命名,如在迴圈裡的遞增(減)變數就可以被命名為 ” i ” 。
Ö 要 儘量採用專案所涉及領域的術語。
Ö 要 採用大小寫混合,提高名字的可讀性。為區分一個識別符號中的多個單詞,把識別符號中的每個單詞的首字母大寫。不採用下劃線作分隔字元的寫法。有兩種適合的書寫方法,適應於不同型別的識別符號:
PasalCasing :識別符號的第一個單詞的字母大寫;
camelCasing :識別符號的第一個單詞的字母小寫。
下表描述了不同型別識別符號的大小寫規則:
識別符號 |
大小寫 |
示例 |
名稱空間 |
Pascal |
namespace Com.Techstar.ProductionCenter |
型別 |
Pascal |
public class DevsList |
介面 |
Pascal |
public interface ITableModel |
方法 |
Pascal |
public void UpdateData() |
屬性 |
Pascal |
Public int Length{…} |
事件 |
Pascal |
public event EventHandler Changed; |
私有欄位 |
Camel |
private string fieldName; |
非私有欄位 |
Pascal |
public string FieldName ; |
列舉值 |
Pascal |
FileMode{Append} |
引數 |
Camel |
public void UpdateData(string fieldName) |
區域性變數 |
Camel |
string fieldName; |
´ 避免 使用縮寫,如果一定要使用,就謹慎使用。同時,應該保留一個標準縮寫的列表,並且在使用時保持一致。
Ö 對常見縮略詞,兩個字母的縮寫要 採用統一大小寫的方式(示例:ioStream ,getIOStream );多字母縮寫採用首字母大寫,其他字母小寫的方式(示例:getHtmlTag );
´ 避免 使用長名字(最好不超過 15 個字母)。
´ 避免 使用相似或者僅在大小寫上有區別的名字。
19 6.2. 各種標示符型別的命名約定
6.2.1 . 程式集命名
Ö 公司域名(Techstar )+ 專案名稱 + 模組名稱(可選),例如:
中心繫統程式集:Techstar.ProductionCenter ;
中心繫統業務邏輯程式集:Techstar. ProductionCenter.Business ;
6.2.2 . 名稱空間命名
Ö 採用和程式集命名相同的方式:公司域名(Techstar )+ 專案名稱 + 模組名稱。 另外,一般情況下建議名稱空間和目錄結構相同。例如:
中心繫統:Techstar.ProductionCenter ;
中心繫統下的使用者控制元件:Techstar.ProductionCenter.UserControl ;
中心繫統業務邏輯:Techstar. ProductionCenter.Business ;
中心繫統資料訪問:Techstar. ProductionCenter.Data ;
6.2.3 . 類和介面命名
Ö 類的名字要 用名詞;
´ 避免使用單詞的縮寫,除非它的縮寫已經廣為人知,如HTTP 。
Ö 介面的名字要 以字母I 開頭。保證對介面的標準實現名字只相差一個“I” 字首,例如對IComponent 的標準實現為Component ;
Ö 泛型型別引數的命名:命名要 為T 或者以T 開頭的描述性名字,例如:
public class List<T>
public class MyClass<TSession>
´ 對同一專案的不同名稱空間中的類,命名避免 重複。避免引用時的衝突和混淆;
6.2.4 . 方法命名
Ö 第一個單詞一般是動詞
Ö 如果方法返回一個成員變數的值,方法名一般為Get+ 成員變數名,如若返回的值 是bool 變數,一般以Is 作為字首。另外,如果必要,考慮用屬性來替代方法,具 體建議見10.1.2 節;
Ö 如果方法修改一個成員變數的值,方法名一般為:Set + 成員變數名。同上,考慮 用屬性來替代方法;
6.2.5 . 變數命名
Ö 按照使用範圍來分,我們程式碼中的變數的基本上有以下幾種型別,類的公有變數;類的私有變數(受保護同公有);方法的引數變數;方法內部使用的區域性變數。這些變數的命名規則基本相同,見識別符號大小寫對照表。區別如下:
i. 類的公有變數按通常的方式命名,無特殊要求;
ii. 類的私有變數採用兩種方式均可:採用加“m” 字首,例如mWorkerName;
iii. 方法的引數變數採用camalString ,例如workerName ;
iv. 方法內部的區域性變數採用camalString ,例如workerName ;
´ 不要 用_ 或& 作為第一個字母;
Ö 儘量要 使用短而且具有意義的單詞;
Ö 單字元的變數名一般只用於生命期非常短暫的變數。i,j,k,m,n 一般用於integer ;c,d,e 一般用於characters ;s 用於string
Ö 如果變數是集合,則變數名要 用複數。例如表格的行數,命名應為:RowsCount ;
Ö 命名元件要 採用匈牙利命名法,所有字首均應遵循同一個元件名稱縮寫列表
縮寫的基本原則是取元件類名各單詞的第一個字母,如果只有一個單詞,則去掉其中的母音,留下子音。縮寫全部為小寫。
元件型別 |
縮寫 |
例子 |
Label |
Lbl |
lblNote |
TextBox |
Txt |
txtName |
Button |
Btn |
btnOK |
ImageButton |
Ib |
ibOK |
LinkButton |
Lb |
lbJump |
HyperLink |
Hl |
hlJump |
DropDownList |
Ddl |
ddlList |
CheckBox |
Cb |
cbChoice |
CheckBoxList |
Cbl |
cblGroup |
RadioButton |
Rb |
rbChoice |
RadioButtonList |
Rbl |
rblGroup |
Image |
Img |
imgBeauty |
Panel |
Pnl |
pnlTree |
TreeView |
Tv |
tvUnit |
WebComTable |
Wct |