代碼編寫規範說明書（c#.net與asp.net）

代碼編寫規範說明書（c#.net與asp.net） 目 錄 1   目的 2   範圍 3   注釋規範 3.1   概述 3.2   自建代碼檔案注釋 3.3   模組（類）注釋 3.4   類屬性注釋 3.5   方法注釋 3.6   代碼間注釋 4   命名總體規則 5   命名規範 5.1    變數（Variable）命名 5.2    常量命名 5.3    類（Class）命名 5.4    介面（Interface）命名 5.5    方法（Method）命名 5.6    名稱空間Namespace）命名 6   編碼規則 6.1    錯誤檢查規則 6.2    大括弧規則 6.3    縮排規則 6.4    小括弧規則 6.5    If Then Else規則 6.6    比較規則 6.7    Case規則 6.8    對齊規則 6.9    單語句規則 6.10    單一功能規則 6.11    簡易功能規則 6.12    明確條件規則 6.13    選用FALSE規則 6.14    獨立賦值規則 6.15    定義常量規則 6.16    模組化規則 6.17    交流規則 7   編程準則 7.1     變數使用 7.2     資料庫操作 7.3     對象使用 7.4     模組設計原則 7.5     結構化要求 7.6     函數傳回值原則 8   程式碼封裝規範 8.1    程式碼封裝的版本號碼 8.2    程式碼封裝的標識 9   代碼的控制 9.1    程式碼程式庫/目錄的建立 9.2    代碼歸檔 10  輸入控制校正規則 10.1    登陸控制 10.2    資料錄入控制 附件1：資料類型縮寫表 附件2：伺服器控制項名縮寫表   1   目的 一.為了統一公司軟體開發設計過程的編程規範 二.使網站開發人員能很方便的理解每個目錄,變數，控制項，類，方法的意義 三.為了保證編寫出的程式都符合相同的規範，保證一致性、統一性而建立的程式編碼規範。 四.編碼規範和約定必須能明顯改善代碼可讀性，並有助於代碼管理、分類範圍適用於企業所有基於.NET平台的軟體開發工作 2   範圍 本規範適用於開發組全體人員，作用於軟體項目開發的代碼編寫階段和後期維護階段。 3   注釋規範 3.1 概述 a)       注釋要求英文及英文的標點符號。 b)       注釋中，應標明對象的完整的名稱及其用途，但應避免對代碼過於詳細的描述。 c)       每行注釋的最大長度為100個字元。 d)       將注釋與注釋分隔字元用一個空格分開。 e)       不允許給注釋加外框。 f)       編碼的同時書寫注釋。 g)       重要變數必須有注釋。 h)       變數注釋和變數在同一行，所有注釋必須對齊，與變數分開至少四個“空格”鍵。 如：int  m_iLevel,m_iCount;     // m_iLevel ....tree level                                     // m_iCount ....count of tree items      string m_strSql;            //SQL i)       典型演算法必須有注釋。 j)       在迴圈和邏輯分支地方的上行必須就近書寫注釋。 k)       程式段或語句的注釋在程式段或語句的上一行 l)       在代碼交付之前，必須刪掉臨時的或無關的注釋。 m)       為便於閱讀代碼，每行代碼的長度應少於100個字元。 3.2      自建代碼檔案注釋 對於自己建立的代碼檔案（如函數、指令碼），在檔案開頭，一般編寫如下注釋： /******************************************************    FileName: Copyright  (c)  2004-xxxx *********公司技術開發部 Writer: create Date: Rewriter: Rewrite Date: Impact: Main Content（Function Name、parameters、returns）               ******************************************************/  3.3     模組（類）注釋 模組開始必須以以下形式書寫模組注釋： ///<summary>               ///Module ID：<模組編號，可以引用系統設計中的模組編號>               ///Depiction：<對此類的描述，可以引用系統設計中的描述>               ///Author：作者中文名               ///Create Date：<模組建立日期，格式：YYYY-MM-DD>               ///</summary> 如果模組只進行部分少量代碼的修改時，則每次修改須添加以下注釋： ///Rewriter Rewrite Date：<修改日期:格式YYYY-MM-DD> Start1：         /* 原代碼內容*/ ///End1：                                將原代碼內容注釋掉，然後添加新代碼使用以下注釋： ///Added by Add date：<添加日期，格式：YYYY-MM-DD> Start2：        ///End2：                                 如果模組輸入輸出參數或功能結構有較大修改，則每次修改必須添加以下注釋： ///<summary>           ///Log ID：<Log編號,從1開始一次增加>           ///depiction：<對此修改的描述>           ///Writer：修改者中文名           ///Rewrite Date：<模組修改日期，格式：YYYY-MM-DD>           ///</summary> 3.4    類屬性注釋 在類的屬性必須以以下格式編寫屬性注釋：             /// <summary>             /// <Properties depiction> /// </summary> 3.5     方法注釋 在類的方法聲明前必須以以下格式編寫注釋              /// <summary>              /// depiction：<對該方法的說明>              /// </summary>              /// <param name="<參數名稱>"><參數說明></param>                  /// <returns>                  ///<對方法傳回值的說明，該說明必須明確說明返回的值代表什麼含義>              /// </returns>              ///Writer：作者中文名              ///Create Date：<方法建立日期，格式：YYYY-MM-DD> 3.6     代碼間注釋 代碼間注釋分為單行注釋和多行注釋： //<單行注釋>            /*多行注釋1              多行注釋2              多行注釋3*/ 代碼中遇到語句塊時必須添加註釋（if,for,foreach,……）,添加的注釋必須能夠說明此語句塊的作用和實現手段（所用演算法等等）。 4    命名總體規則          名字應該能夠標識事物的特性。          名字一律使用英文單詞，而不能為拼音。          名字盡量不使用縮寫，除非它是眾所周知的。          名字可以有兩個或三個單片語成，但不應多於三個，控制在3至30個字母以內。          在名字中，多個單詞用大寫第一個字母（其它字母小寫）來分隔。例如：IsSuperUser。          名字盡量使用首碼而不是尾碼。          名字中的單詞盡量使用名詞，如有動詞，也盡量放在後面。例如：FunctionUserDelete（而不是FunctionDeleteUser）。 5    命名規範 5.1   變數（Variable）命名 a)    程式檔案(*.cs)中的變數命名          程式中變數名稱 = 變數的首碼 +代表變數含意的英文單詞或單詞縮寫。         類別模組級的變數請用“m_” +資料類型縮寫作為首碼（其中，m 為“memory”縮寫，資料類型縮寫見附件中的《資料類型縮寫表》）。  public class hello {                private string m_strName;                private DateTime m_dtDate;             }         類的屬性所對應的變數，採用屬性名稱前加“m_”+ 類型縮寫 首碼的形式 public class hello {         private string m_strName;         public string Name         {          get {       return m_strName; } } } 過程級的變數使用類型縮寫首碼 public class hello {         void say()         {           string strSayWord; } }          過程的參數使用“p_”+ 類型縮寫作為首碼（其中，p 為“parameter”縮寫）      public class hello      {          void say(string p_strSayWord)          {          }      }   補充說明：     針對異常捕獲過程中的Exception變數命名，在沒有衝突的情況下，統一命名為exp； 如果有衝突的情況下，可以用“exp”+ 標誌名稱，如：expSql。 Try {          //your code         try { //code } catch(Exception exp) { //your code } } catch(Exception expSql) {        //your code } 補充：如果捕獲異常不需要作任何處理，則不需要定義Exception執行個體。 例： try {      //your code } catch( Exception exp) { }     鑒於大多數名稱都是通過串連若干單詞構造的，請使用大小寫混合的格式以簡化它們的閱讀。每個單詞的第一個字母都是大寫. 即使對於可能僅出現在幾個程式碼中的生存期很短的變數，仍然使用有意義的名稱。僅對於短迴圈索引使用單字母變數名，如 i 或 j。   在變數名中使用互補對，如 min/max、begin/end 和 open/close。   不要使用原義數字或原義字串，如 For (i = 1;i <= 7;i++)。而是使用命名常數，如 For (i = 1;i <= NUM_DAYS_IN_WEEK;i++) 以便於維護和理解。 b)    控制項命名 控制項命名 = 控制項名稱前二到三個字母 + 名稱，如Labl控制項（labUserName） 5.2    常量命名 常量名也應當有一定的意義，格式為 NOUN 或 NOUN_VERB。常量名均為大寫，字之間用底線分隔。 例：         private const bool   WEB_ENABLEPAGECACHE_DEFAULT           = true;         private const int    WEB_PAGECACHEEXPIRESINSECONDS_DEFAULT = 3600;         private const bool   WEB_ENABLESSL_DEFAULT                 = false; 註： 變數名和常量名最多可以包含 255 個字元，但是，超過 25 到 30 個字元的名稱比較笨拙。此外，要想取一個有實際意義的名稱，清楚地表達變數或常量的用途，25 或 30 個字元應當足夠了。 5.3      類（Class）命名 a)       名字應該能夠標識事物的特性。 b)       名字盡量不使用縮寫，除非它是眾所周知的。 c)       名字可以有兩個或三個單片語成，但通常不應多於三個。 d)       在名字中，所有單詞第一個字母大寫。例如  IsSuperUser，包含ID的，ID全部大寫，如CustomerID。 e)       使用名詞或名詞短語命名類。 f)       少用縮寫。 g)       不要使用底線 (_)。 例：    public class FileStream public class Button public class String 5.4      介面（Interface）命名       和類命名規範相同，唯一區別是  介面在名字前加上“I”首碼       例：       interface IDBCommand;      interface IButton; 5.5      方法（Method）命名      和類命名規範相同。 5.6      命名空間（NameSpace）命名 和類命名規範相同。 6        編碼規則 6.1      錯誤檢查規則 a)     編程中要考慮函數的各種執行情況，儘可能處理所有流程情況。 b)     檢查所有的系統調用的錯誤資訊，除非要忽略錯誤。 c)     將函數分兩類：一類為與螢幕的顯示無關， 另一類與螢幕的顯示有關。對於與螢幕顯示無關的函數，函數通過傳回值來報告錯誤。對於與螢幕顯示有關的函數，函數要負責向使用者發出警告，並進行錯誤處理。 d)     錯誤處理代碼一般放在函數末尾。 e)     對於通用的錯誤處理，可建立通用的錯誤處理函數，處理常見的通用的錯誤。 6.2      大括弧規則 將大括弧放置在關鍵詞下方的同列處，例如： if ($condition)       while ($condition) {                  {       ...                   ... }                  } 6.3      縮排規則 使用一個“Tab”為每層次縮排。例如： function func()    {       if (something bad)       {          if (another thing bad)          {             while (more input)             {             }          }       }    } 6.4      小括弧規則 a)     不要把小括弧和關鍵詞（if 、while等）緊貼在一起，要用空格隔開它們。 b)     不要把小括弧和函數名緊貼在一起。 c)     除非必要，不要在Return返回語句中使用小括弧。因為關鍵字不是函數，如果小括弧緊貼著函數名和關鍵字，二者很容易被看成是一體的。 6.5      If Then Else規則 如果你有用到else if 語句的話，通常最好有一個else塊以用於處理未處理到的其他情況。可以的話放一個記錄資訊注釋在else處，即使在else沒有任何的動作。其格式為： if (條件1)                 // 注釋    {    }    else if (條件2)            // 注釋    {    }    else                           // 注釋    {    } 註：if 和迴圈的嵌套最多允許4層 6.6      比較規則 總是將恒量放在等號/不等號的左邊。一個原因是假如你在等式中漏了一個等號，語法檢查器會為你報錯。第二個原因是你能立刻找到數值而不是在你的運算式的末端找到它。例如： if ( 6 == $errorNum ) ... 6.7      Case規則 default case總應該存在，如果不允許到達，則應該保證：若到達了就會觸發一個錯誤。Case的選擇條件最好使用int或string類型。 6.8      對齊規則 變數的申明和初始化都應對齊。例如：    int       m_iCount;    int       i,j;    float     m_fIncome,m_fPay;      m_iCount  = 0;    i         = 1;    m_fIncome = 0.3; 6.9      單語句規則 除非這些語句有很密切的聯絡，否則每行唯寫一個語句。 6.10     單一功能規則 原則上，一個程式單元（函數、常式、方法）只完成一項功能。 6.11     簡易功能規則 原則上，一個程式單元的代碼應該限制在一頁內（25~30行）。 6.12     明確條件規則 不要採用預設值測試非零值。例如：使用“if  ( 0 !=  f( ) )”而不用“if  ( f( ) )”。 6.13     選用FALSE規則 大部分函數在錯誤時返回FALSE、0或NO之類的值，但在正確時傳回值就不定了（不能用一個固定的TRUE、1或YES來代表），因此檢測一個布爾值時應該用  FALSE、0、NO之類的不等式來代替。例如：使用“if  ( FALSE !=  f( ) )” 而不用“if  (TRUE ==  f( ) )”。 6.14      獨立賦值規則 嵌入式賦值不利於理解程式，同時可能回造成意想不到的副作用，應盡量編寫獨立的指派陳述式。例如：使用“a = b + c ;  e = a + d;”而不用“e = ( a = b + c ) + d ”。 6.15      定義常量規則 對於代碼中引用的常量（尤其是數字），應該define成一個大寫的名字，在代碼中引用名字而不直接引用值。 6.16      模組化規則 某一功能，如果重複實現一遍以上，即應考慮模組化，將它寫成通用函數。並向小組成員發布。同時要儘可能利用其它人的現成模組。 6.17       交流規則 共用別人的工作成果，向別人提供自己的工作成果。 在具體任務開發中，如果有其它的編碼規則，則在相應的軟體開發計劃中予   以明確定義。 7       編程準則 7.1      變數使用 a)       不允許隨意定義全域變數。 b)       一個變數只能有一個用途；變數的用途必須和變數的名稱保持一致。 c)       所有變數都必須在類和函數最前面定義，並分類排列。 7.2      資料庫操作 a)       尋找資料庫表或視圖時，只能取出確實需要的那些欄位。 b)       使用無關聯子查詢，而不要使用關聯子查詢。 c)       清楚明白地使用列名，而不能使用列的序號。 d)       用事務保證資料的完整性。 7.3      對象使用 a)       儘可能晚地建立對象，並且儘可能早地釋放它。 7.4      模組設計原則 a)       不允許隨意定義公用的函數和類。 b)       函數功能單一，不允許一個函數實現兩個及兩個以上的功能。 c)       不能在函數內部使用全域變數，如要使用全域變數，應轉化為局部變數。 d)       函數與函數之間只允許存在內含項目關聯性，而不允許存在交叉關係。即兩者之間只存在單方向的調用與被調用，不存在雙向的調用與被調用。 7.5      結構化要求 a)     禁止出現兩條等價的支路。 例如：if (a == 2)        else if (a== 3)              //        else if (a == 2)              //        else            // b)     避免使用GOTO語句 c)     用 IF 語句來強調只執行兩組語句中的一組。禁止 ELSE GOTO 和 ELSE RETURN。 d)     用 CASE 實現多路分支 e)     避免從迴圈引出多個出口。 f)     函數只有一個出口。 g)     不使用條件指派陳述式。 h)     避免不必要的分支。 i)     不要輕易用條件分支去替換邏輯運算式 7.6      函數傳回值原則 1）  函數傳回值 避免使用結構體等複雜類型 使用bool類型：該函數只需要獲得成功或者失敗的返回資訊時候 使用int 類型：錯誤碼用負數表示，成功返回0 8      程式碼封裝規範 本項目中，每個任務在完成一個穩定的版本後，都應打包並且歸檔。 8.1      程式碼封裝的版本號碼           項目中，程式碼封裝的版本號碼由圓點隔開的兩個數字組成，第一個數字表示發行號，第二個數字表示該版的修改號。具體用法如下： 1)     當程式碼封裝初版時，版本號碼為 V1.00； 2)     當程式碼封裝被局部修改或bug修正時，發行號不變，修改號第二個數字增1。例如，對初版程式碼封裝作了第一次修訂，則版本號碼為 V1.01； 3)     當程式碼封裝在原有的基礎上增加部分功能，發行號不變，修改號第一個數字增1，例如，對V1.12版的基礎上增加部分功能，則新版本號碼為 V1.20； 4)     當程式碼封裝有重要修改或局部修訂累積較多導致程式碼封裝發生全域變化時，發行號增1。例如，在 V1.15 版的基礎上作了一次全面修改，則新版本號碼為 V2.00。 8.2      程式碼封裝的標識          本項目所產生的程式碼封裝都有唯一、特定的編碼，其構成如下： S-項目標識-程式碼封裝類型-版本號碼/序號          其中： 1)       S：本項目的標識，表明本項目是“XXXX”。 2)       項目標識：簡要標識本項目，此標識適用於整個項目的文檔。 3)       程式碼封裝類型：取自以下表的兩位字母編碼。 4)       版本號碼：本程式碼封裝的版本號碼。 5)       序號：四位元字編碼，指明該程式碼封裝在項目程式碼程式庫的總序號。          例如： 一個Windows下RAR源碼的壓縮程式碼封裝命名為：  S-XXXX-WS-V1.02/0001 項目的程式碼封裝分類表 類 型 編 碼 注 釋 RAR包 （web） 源碼檔案 WS 原始碼檔案包  編譯檔案 WB 編譯檔案包  安裝檔案 WI 安裝檔案包  源碼代碼 + 安裝檔案 WA 原始碼和安裝檔案包   項目中所有程式碼封裝的標識清單將在《項目開發計劃》中予以具體定義。 9     代碼的控制 9.1     程式碼程式庫/目錄的建立 項目負責人在VSS中建立項目的文件庫目錄，即為“Software”目錄，以便快速查詢。 9.2    代碼歸檔 所有代碼在完成一個穩定的版本後，項目負責人都應打包後，存放於VSS中該目的“Software”目錄下，並且依據程式碼封裝的命名規範為程式碼封裝分配一個唯一名稱。 10  輸入控制校正規則 10.1 登陸控制 使用者登陸ID和登陸密碼，要限定輸入長度範圍，必須檢查輸入合法性。 10.2 資料錄入控制 a)     TextBox輸入 1、  要保持使用者輸入和資料庫接收的長度一致 2、  必須進行輸入合法性校正 如：E_mail格式   XXX@XXX.XXX...         電話格式     020-12345678      (020)12345678         郵遞區號是六位 b) 除CheckBox、RadioButton外，禁止在DataGrid內嵌入其他編輯控制項，用以添加編輯資料 11. 資料庫命名規範: SqlServer命名規範 使用本系統遵循以下命名規範： 1、表命名：用一個或三個以下英文單片語成，單字首大寫，如：DepartmentUsers； 2、表主鍵名稱為：表名+ID，如Document表的主鍵名為：DocumentID 3、預存程序命名：表名+方法,如：p_my_NewsAdd,p_my_NewsUpdate; 4、視圖命名：View_表名，如：ViewNews; 5、Status為表中狀態的列名，預設值為0，在表中刪除操作將會改變Status的值而不真實刪除該記錄； 6、Checkintime為記錄添加時間列，預設值為系統時間； 7、表、預存程序、視圖等對象的所有都為dbo，不要使用資料庫使用者名稱，這樣會影響資料庫使用者的更改。 附件1：資料類型縮寫表   資料類型 縮寫 string str int i char chr sbyte sb byte bt uint ui long l ulong ul float f double d bool b decimal dec   附註：資料庫伺服器命名規範，控制項名縮寫+控制項作用單詞的全稱,如：btnNext, txtPassword(密碼文字框)，txtRPassword(密碼確認文字框)，單詞的第一個字母必須大寫如果有多個單詞，則為控制項縮寫+控制項作用的第一個單詞+第二個單詞的全稱，每個單詞名的第一個字母必須大寫 附件2：伺服器控制項名縮寫表  a、web控制項 web控制項名 縮寫 AdRotator art Button btn Calendar cd CheckBox chk CheckBoxList chkl CompareValidator cpv CustomValidator ctv DataGrid dg DataList dl DropDownList ddl HyperLink hl Image img ImageButton Ibtn Label lab LinkButton lbtn ListBox lst Panel pl PlaceHolder ph RadioButton rb RadioButtonList rbl RangeValidator rv RegularExpressionValidator rev Repeater rp RequiredFieldValidator rfv Table tb TableCell tc TableRow tr TextBox txt ValidationSummary vs XML XML            b、html控制項 html控制項名 縮寫 HtmlAnchor hah HtmlButton hbtn HtmlForm hform HtmlGenericControl hgc HtmlImage himg HtmlInputButton（按鈕） htxt HtmlInputButton（重設） hrbtn HtmlInputButton（提交） hcbtn HtmlInputCheckBox hick HtmlInputFile hifile HtmlInputHidden hihidden HtmlInputImage hiimg HtmlInputRadioButton hirb HtmlInputText（密碼） hpwd HtmlInputText（文本） hitxt HtmlSelect hslt HtmlTable htab HtmlTableCell htc HtmlTableRow htr HtmlTextArea htxta c.ADO.NET控制項命名規範 類型 首碼 樣本 Connection con conNorthwind Command cmd cmdReturnProducts Parameter parm parmProductID DataAdapter dad dadProducts DataReader dtr dtrProducts DataSet dst dstNorthWind DataTable dtbl dtblProduct DataRow drow drowRow98 DataColumn dcol dcolProductID DataRelation drel drelMasterDetail DataView dvw dvwFilteredProducts