《團隊-排課軟件-代碼設計規範》
C#代碼編程規範
目錄
第一章 概述.... 3
規範制定原則... 3
文件命名組織... 3
1.1文件命名... 3
1.2文件註釋... 3
第二章 程序註釋.... 5
2.1 註釋概述... 5
2.2 文檔型註釋... 5
2.3 類註釋... 6
2.4 函數註釋... 6
2.5接口註釋... 6
2.6 單行註釋... 6
2.7 模塊註釋... 7
2.8方法註釋... 7
2.9 變量註釋... 8
第三章 命名規範.... 9
3.1命名概述... 9
3.2類... 9
3.3接口... 10
3.4靜態變量... 10
3.5全局變量... 10
3.6 參數... 11
3.7 方法... 11
3.8字段... 11
3.9函數... 12
第一章 概述
規範制定原則
1 方便代碼的交流和維護。
2 不影響編碼的效率，不與大眾習慣沖突,保證一致性統一性。
3 使代碼更美觀、閱讀更方便,代碼可讀性,並有助於代碼管理。
4 使代碼的邏輯更清晰、更易於理解。
5為了統一公司軟件開發設計過程的編程規範
文件命名組織
1.1文件命名
1 文件名遵從Pascal命名法，無特殊情況，擴展名小寫。
2 使用統一而又通用的文件擴展名： C# 類 .cs
3文件命名原則是更容易區分不同的文件類型，在文件名前增加三字符的前綴，前綴字母一律為小寫
例如：
一個窗體文件可以增加frm前綴，frmForm1.cs
4文件主體名必須用名詞或動名詞，且主體名必須是單詞首字大寫的方式表示
例如：
證件登記的窗體可以命名為frmPatientReg.cs，一個取消證件登記的窗體可以命名為frmCancelPatientReg.cs
5文件名必須采用在不影響原意表達時盡量采用單詞縮寫的形式命名，以達到文件名的簡潔明了的命名目的
1.2文件註釋
1 在每個文件頭必須包含以下註釋說明
/*----------------------------------------------------------------
// Copyright (C) 2012 科技集團
// 版權所有。
// 文件名：
// 文件功能描述：
// 創建標識：
// 創建描述
// 修改標識：
// 修改描述：
//----------------------------------------------------------------*/
/*********************************************************************************
* File: *
* PermissionPrincipal.cs *
* Description: *
* 方法權限檢測認證類
* Author: *
* qq *
* Finish DateTime: *
* 2012年2月28日 *
* History: *
***********************************************************************************/
文件功能描述只需簡述。
創建標識和修改標識由創建或修改人員的名字、拼音或英文名加日期組成。
如：屈原/qu yuan2012年2月28日
一天內有多個修改的只需做一個在註釋說明中做一個修改標識就夠了。
在所有的代碼修改處加上修改標識的註釋。
第二章 程序註釋
2.1 註釋概述
1、修改代碼時，總是使代碼周圍的註釋保持最新。
2、在每個例程的開始，提供標準的註釋樣本以指示例程的用途、假設和限制很有幫助。註釋樣本應該是解釋它為什麽存在和可以做什麽的簡短介紹.
3、避免在代碼行的末尾添加註釋；行尾註釋使代碼更難閱讀。不過在批註變量聲明時，行尾註釋是合適的；在這種情況下，將所有行尾註釋在公共制表位處對齊。
4 、避免雜亂的註釋，如一整行星號。而是應該使用空白將註釋同代碼分開。
5 、避免在塊註釋的周圍加上印刷框。這樣看起來可能很漂亮，但是難於維護。
6 、在部署發布之前，移除所有臨時或無關的註釋，以避免在日後的維護工作中產生混亂。
7 、如果需要用註釋來解釋復雜的代碼節，請檢查此代碼以確定是否應該重寫它。
盡一切可能不註釋難以理解的代碼，而應該重寫它。盡管一般不應該為了使代碼更簡單以便於人們使用而犧牲性能，但必須保持性能和可維護性之間的平衡。
8 、在編寫註釋時使用完整的句子。註釋應該闡明代碼，而不應該增加多義性。
9 、在編寫代碼時就註釋，因為以後很可能沒有時間這樣做。另外，如果有機會復查已編寫的代碼，在今天看來很明顯的東西六周以後或許就不明顯了。
10 、避免多余的或不適當的註釋，如幽默的不主要的備註。
11、 使用註釋來解釋代碼的意圖。它們不應作為代碼的聯機翻譯。
12、 註釋代碼中不十分明顯的任何內容。
13 、為了防止問題反復出現，對錯誤修復和解決方法代碼總是使用註釋，尤其是在團隊環境中。
14 、對由循環和邏輯分支組成的代碼使用註釋。這些是幫助源代碼讀者的主要方面。
15 、在整個應用程序中，使用具有一致的標點和結構的統一樣式來構造註釋。
16 、用空白將註釋同註釋分隔符分開。在沒有顏色提示的情況下查看註釋時，這樣做會使註釋很明顯且容易被找到。
17 、在所有的代碼修改處加上修改標識的註釋。
18 、為了是層次清晰，在閉合的右花括號後註釋該閉合所對應的起點。
namespace Langchao.Procument.Web
{
} // namespace Langchao.Procument.Web
19 、典型算法必須有註釋
2.2 文檔型註釋
該類註釋采用.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)
{ }
2.3 類註釋
類屬性註釋
在類的屬性必須以以下格式編寫屬性註釋：
/// <summary>
///Class name 類名
/// <Properties depiction> 屬性描述
/// Author 作者
/// Creation date 創建日期
/// Modified by修改者
/// Modified date 修改日期
/// Modify the description 修改描述
/// Remarks 備註
/// </summary>
例如:
/// <summary>
/// Class name： 人員信息實體類層
/// depiction： 類層用於人員信息錄入
/// Author ：qq
/// Creation date ：2012-3-5
/// Modified by ：qq
/// Modified date:2012-3-5
/// Modify the description:實體類層部分屬性的添加 添加了一個屬性
/// Remarks: 屬性添加修改
/// </summary>
public class cls_Personnel
{
}
2.4 函數註釋
標準的函數註釋格式；
//==================================================================
//函數名：
//作者：
//日期：
//功能：
//輸入參數：
//返回值：
//修改記錄：
//==================================================================
示例：
//==================================================================
//函數名： RecordIsExist
//作者： qq
//日期： 2012-03-05
//功能： 判斷當前待插入或更新的記錄在原表中是否已經存在
//輸入參數：bm (表名） 待查找的 表的名字
// zdm (字段名）在表中待查找的字段
// zdz(字段值） 需要比較的字段的值
//返回值： 類型（boolean)
// 返回true表示當前表中存在一條跟待插入的記錄一樣的記錄；
// 返回false表示當前待插入的記錄在表中不存在。
//修改記錄：
//==================================================================
2.5接口註釋
接口只包含方法、委托或事件的簽名。方法的實現是在實現接口的類中完成的，
/// <summary>
/// name：
/// depiction：
/// Author ：qq
/// Creation date ：2012-3-5
/// Modified by ：qq
/// Modified date:2012-3-5
/// Modify the description:
/// </summary>
public interface IComponent
{ }
2.6 單行註釋
該類註釋用於
1 方法內的代碼註釋。如變量的聲明、代碼或代碼段的解釋。註釋示例：
//
// 註釋語句
//
private int number;
或
// 註釋語句
private int number;
2 方法內變量的聲明或花括號後的註釋, 註釋示例：
if ( 1 == 1) // always true
{
statement;
} // always true
2.7 模塊註釋
模塊開始必須以以下形式書寫模塊註釋：
///<summary>
///Module ID：<模塊編號，可以引用系統設計中的模塊編號>
///Depiction：<對此類的描述，可以引用系統設計中的描述>
///Author：作者中文名
///Create Date：<模塊創建日期，格式：YYYY-MM-DD>
///</summary>
如果模塊只進行部分少量代碼的修改時，則每次修改須添加以下註釋：
///Modify Date：<修改日期:格式YYYY-MM-DD>Start1：
/* 原代碼內容*/
///End1：
將原代碼內容註釋掉，然後添加新代碼使用以下註釋：
///Added by Add date：<添加日期，格式：YYYY-MM-DD>Start2：
///End2：
如果模塊輸入輸出參數或功能結構有較大修改，則每次修改必須添加以下註釋：
///<summary>
///Log ID：<Log編號,從1開始一次增加>
///depiction：<對此修改的描述>
///Author：修改者中文名
///Modify Date：<模塊修改日期，格式：YYYY-MM-DD>
///</summary>
2.8方法註釋
在類的方法聲明前必須以以下格式編寫註釋
/// <summary>
/// depiction：<對該方法的說明>
/// </summary>
/// <paramname="<參數名稱>"><參數說明></param>
/// <returns>
///<對方法返回值的說明，該說明必須明確說明返回的值代表什麽含義>
/// </returns>
///Author：作者中文名
///Create Date：<方法創建日期，格式：YYYY-MM-DD>
/// <summary>
/// depiction：綁定信息
/// Author： qq 2012.2.28
/// </summary>
/// <param name="cls">參數cls</param>
/// <param name="RecordCount">返回記錄</param>
/// <returns>返回記錄</returns>
public override ArrayList ApproveList_NotCommit(cls_Approve cls, out int RecordCount)
{
}
- 在公用類庫中的公用方法需要在一般方法的註釋後添加作者、日期及修改記錄信息，統一采用XML標簽的格式加註，標簽如下：
<Author></Author> 作者
<CreateDate></CreateDate> 建立日期
<RevisionHistory> 修改記錄
<ModifyBy></ModifyBy> 修改作者
<ModifyDate></ModifyDate> 修改日期
<ModifyReason></ModifyReason> 修改理由
<ModifyBy></ModifyBy> 修改作者
<ModifyDate></ModifyDate> 修改日期
<ModifyReason></ModifyReason> 修改理由
<ModifyBy></ModifyBy> 修改作者
<ModifyDate></ModifyDate> 修改日期
<ModifyReason></ModifyReason> 修改理由
</RevisionHistory>
<LastModifyDate></LastModifyDate> 最後修改日期
2一個代碼文件如果是由一人編寫，則此代碼文件中的方法無需作者信息，非代碼文件作者在此文件中添加方法時必須要添加作者、日期等註釋
3修改任何方法，必須要添加修改記錄的註釋
2.9 變量註釋
定義變量時需添加變量註釋，用以說明變量的用途
- class級變量應以三條斜線的形式註釋
- 方法級的變量註釋可以放在變量聲明語句的後面，與前後行變量聲明的註釋左對齊，註釋與代碼間以Tab隔開。
第三章 命名規範
3.1命名概述
名稱應該說明“什麽”而不是“如何”。通過避免使用公開基礎實現（它們會發生改變）的名稱，可以保留簡化復雜性的抽象層。例如，可以使用 GetNextStudent()，而不是 GetNextArrayElement()。
命名原則是：
選擇正確名稱時的困難可能表明需要進一步分析或定義項的目的。使名稱足夠長以便有一定的意義，並且足夠短以避免冗長。唯一名稱在編程上僅用於將各項區分開。表現力強的名稱是為了幫助人們閱讀；因此，提供人們可以理解的名稱是有意義的。不過，請確保選擇的名稱符合適用語言的規則和標準。
以下幾點是推薦的命名方法。
1、避免容易被主觀解釋的難懂的名稱，如方面名 AnalyzeThis()，或者屬性名 xxK8。這樣的名稱會導致多義性。
2、在類屬性的名稱中包含類名是多余的，如 Book.BookTitle。而是應該使用 Book.Title。
3、只要合適，在變量名的末尾或開頭加計算限定符（Avg、Sum、Min、Max、Index）。
4、在變量名中使用互補對，如 min/max、begin/end 和 open/close。
5、布爾變量名應該包含 Is，這意味著 Yes/No 或 True/False 值，如 fileIsFound。
6、在命名狀態變量時，避免使用諸如 Flag 的術語。狀態變量不同於布爾變量的地方是它可以具有兩個以上的可能值。不是使用 documentFlag，而是使用更具描述性的名稱，如 documentFormatType。 （此項只供參考）
7、即使對於可能僅出現在幾個代碼行中的生存期很短的變量，仍然使用有意義的名稱。僅對於短循環索引使用單字母變量名，如 i 或 j。 可能的情況下，盡量不要使用原義數字或原義字符串，如
For i = 1 To 7。而是使用命名常數，如 For i = 1 To NUM_DAYS_IN_WEEK 以便於維護和理解。
為一個名稱空間名。
3.2類
1、使用 Pascal 大小寫。
2、用名詞或名詞短語命名類。
3、使用全稱避免縮寫，除非縮寫已是一種公認的約定，如URL、HTML
4 、不要使用類型前綴，如在類名稱上對類使用 C 前綴。例如，使用類名稱 FileStream，而不是
CFileStream。
5 、不要使用下劃線字符 (_)。
6 、有時候需要提供以字母 I 開始的類名稱，雖然該類不是接口。只要 I 是作為類名稱組成部分的整個單詞的第一個字母，這便是適當的。例如，類名稱 IdentityStore 是適當的。在適當的地方，使用復合單詞命名派生的類。派生類名稱的第二個部分應當是基類的名稱。例如，ApplicationException 對於從名為 Exception 的類派生的類是適當的名稱，原因ApplicationException 是一種Exception。請在應用該規則時進行合理的判斷。例如，Button 對於從 Control 派生的類是適當的名稱。盡管按鈕是一種控件，但是將 Control 作為類名稱的一部分將使名稱不必要地加長。
public class FileStream
public class Button
public class String
泛型類型參數的命名：命名要為T或者以T開頭的描述性名字，例如：
public class List<T>
public class MyClass<TSession>
′ 對同一項目的不同命名空間中的類，命名避免重復。避免引用時的沖突和混淆；
3.3接口
以下規則概述接口的命名指南：
1、用名詞或名詞短語，或者描述行為的形容詞命名接口。例如，接口名稱 IComponent 使用描述性
名詞。接口名稱 ICustomAttributeProvider 使用名詞短語。名稱 IPersistable 使用形容詞。
2、使用 Pascal 大小寫。
3、少用縮寫。
4、給接口名稱加上字母 I 前綴，以指示該類型為接口。在定義類/接口對（其中類是接口的標準
實現）時使用相似的名稱。兩個名稱的區別應該只是接口名稱上有字母 I 前綴。
5、不要使用下劃線字符 (_)。
6、當類是接口的標準執行時，定義這一對類/接口組合就要使用相似的名稱。兩個名稱的不同之處
只是接口名前有一個I前綴。
以下是正確命名的接口的示例。
public interface IServiceProvider
public interface IFormatable
以下代碼示例闡釋如何定義 IComponent 接口及其標準實現 Component 類。
public interface IComponent
{
// Implementation code goes here.
}
public class Component: IComponent
{
// Implementation code goes here.
}
3.4靜態變量
全局變量/靜態變量定義全部要大寫 如：
Public static int SMS_TYPE=2;
定義部分也可以大小寫。
如：public static string VOSMS_UserName=”000000”
單詞與單詞之間加“-”分隔符
靜態變量前加s_(表示static
例如：
Void init (…)
Static int s_initValue;//靜態變量
3.5全局變量
使用全局變量加前綴g_(表示global)
例如
Int g_howManyPeople;//全局變量
String UserName
3.6 參數
以下規則概述參數的命名指南：
1、使用描述性參數名稱。參數名稱應當具有足夠的描述性，以便參數的名稱及其類型可用於在大多數情況下確定它的含義。
2、對參數名稱使用 Camel 大小寫。
3、 使用描述參數的含義的名稱，而不要使用描述參數的類型的名稱。開發工具將提供有關參數的類型的有意義的信息。因此， 通過描述意義，可以更好地使用參數的名稱。少用基於類型的參數名稱，僅在適合使用它們的地方使用它們。
4、不要使用保留的參數。保留的參數是專用參數，如果需要，可以在未來的版本中公開它們。相反，如果在類庫的未來版本中需要更多的數據，請為方法添加新的重載。
5、不要給參數名稱加匈牙利語類型表示法的前綴。
以下是正確命名的參數的示例。
Type GetType(string typeName)
string Format(string format, args() As object)
3.7 方法
以下規則概述方法的命名指南：
1 使用動詞或動詞短語命名方法。方法名的主體應該使用大小寫混合形式，並且應該足夠長以描述它的作用。而且，方法名應該以一個動詞起首，如 InitNameArray 或 CloseDialog。
對於頻繁使用的或長的項，推薦使用標準縮略語以使名稱的長度合理化。一般來說，超過 32 個字符的變量名在 VGA 顯示器上讀起來就困難了。
當使用縮略語時，要確保它們在整個應用程序中的一致性。在一個工程中，如果一會兒使用 Cnt， 一會兒使用 Count，將導致不必要的混淆。
2 使用 Pascal 大小寫。
3 以下是正確命名的方法的實例。
RemoveAll()
GetCharArray()
Invoke()
3.8字段
以下規則概述字段的命名指南：
1、private、protected 使用 Camel 大小寫。
2、public 使用 Pascal 大小寫。
3、拼寫出字段名稱中使用的所有單詞。僅在開發人員一般都能理解時使用縮寫。字段名稱不
要使用大寫字母。下面是正確命名的字段的示例。
class SampleClass
{
string url;
string destinationUrl;
}
4、不要對字段名使用匈牙利語表示法。好的名稱描述語義，而非類型。
5、不要對字段名或靜態字段名應用前綴。具體說來，不要對字段名稱應用前綴來區分靜態和非靜態字段。例如，應用 g_ 或 s_ 前綴是不正確的。
6、對預定義對象實例使用公共靜態只讀字段。如果存在對象的預定義實例，則將它們聲明為
對象本身的公共靜態只讀字段。使用 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;
}
}
}
靜態字段 以下規則概述靜態字段的命名指南：
1、使用名詞、名詞短語或者名詞的縮寫命名靜態字段。
2、使用 Pascal 大小寫。
3、對靜態字段名稱使用匈牙利語表示法前綴。
4、建議盡可能使用靜態屬性而不是公共靜態字段。
3.9函數
用大寫字母開頭的單詞組合以動詞為開始或者 動詞+名詞，每個單詞第一個字母必須大寫。單詞之間不加“-”。
例如：
Public static string GetOrderStatus(int sendMode, int statusID)
函數名和方法名以動詞開始 如：intNameArray() 和CloseDialog().
構造函數的名字與類同名 無返回值類型(這與返回值類型為void的函數不同)
《團隊-排課軟件-代碼設計規範》