日企新員工培訓(xùn)-C#編碼規(guī)范(范本).doc

宏圖財(cái)務(wù) HFS文檔編號(hào)File No.HTFS-S-20050501文檔名稱File Name中文LocalC編碼規(guī)范版本VersionV 1.5英文EnglishCode Specification for C密級(jí)Secret Level內(nèi)部(INSIDE)存放位置Locate作者AuthorBenC編碼規(guī)范Code Specification for C（僅供內(nèi)部使用 Only for inside of HTFS）作者：徐長(zhǎng)龍 (Ben)日期：2005年5月11日宏圖財(cái)務(wù) HFS版權(quán)所有 不得復(fù)制Copyright by HTFS 2004,All rights reservedC#編碼規(guī)范文檔修改記錄Code Specification for C#Revision History版本號(hào)Version日期日期Revision Date修改理由Summary/Comment修改作者Revision By修改的頁(yè)數(shù)Revision Pages1.02005/5/11CreateBenALL1.12005/5/12AddLijun1.22005-05-19BenALL1.32005-05-24增加公用方法注釋規(guī)范Ben161.42005-07-27Ben1.52006-01-121. 文檔修改記錄塊格式變更，將注釋改為修改理由。2. 文件頭部注釋的修改記錄中增加修改理由。3. 方法注釋增加修改記錄的注釋格式。4. 方法級(jí)變量聲明注釋可以在變量聲明的語(yǔ)句后注釋，與前后行聲明語(yǔ)句左對(duì)齊。Ben13-18目錄一、目的4二、適用范圍4三、命名空間4四、文件命名規(guī)范5五、控件命名規(guī)范65.1 Win Form內(nèi)部控件命名規(guī)范75.2 Web Form內(nèi)部控件命名規(guī)范85.3 C#數(shù)據(jù)組件命名規(guī)范95.4 C#菜單命名規(guī)范10六、變/常量命名規(guī)范116.1變量范圍前綴116.2變量類型前綴11七、方法命名規(guī)范12八、代碼注釋規(guī)范138.1代碼注釋約定138.2模塊頭部注釋規(guī)范138.3方法注釋規(guī)范148.4代碼行注釋規(guī)范168.5變量注釋規(guī)范17九、其它規(guī)范179.1編程風(fēng)格179.2資源釋放199.3錯(cuò)誤處理：209.4其他21一、目的1. 使用統(tǒng)一編碼規(guī)范的主要原因，是使應(yīng)用程序的結(jié)構(gòu)和編碼風(fēng)格標(biāo)準(zhǔn)化，以便于閱讀和理解這段編碼。2. 好的編碼約定可使源代碼嚴(yán)謹(jǐn)、可讀性強(qiáng)且意義清楚，與其它語(yǔ)言約定相一致，并且盡可能的直觀。 回目錄二、適用范圍1. 本規(guī)范不適用于數(shù)據(jù)庫(kù)開(kāi)發(fā)規(guī)范，數(shù)據(jù)庫(kù)開(kāi)發(fā)相關(guān)規(guī)范請(qǐng)參考相關(guān)文檔；2. 本規(guī)范主要以C#為開(kāi)發(fā)語(yǔ)言的規(guī)范，為開(kāi)發(fā)部的原則性規(guī)范；3. 由于本規(guī)范是為撰寫(xiě)程序而設(shè)計(jì)，所以適用于一切有關(guān)程序撰寫(xiě)的工作事項(xiàng)。對(duì)于具體的每個(gè)項(xiàng)目，可能需要對(duì)之進(jìn)行裁剪和補(bǔ)存。 補(bǔ)存的內(nèi)容確認(rèn)之后公用的內(nèi)容要更新到此規(guī)范中；4. 適用人員：所有開(kāi)發(fā)人員及代碼品管人員；5. 適用產(chǎn)品：所有以C#編寫(xiě)的代碼。 回目錄三、命名空間命名空間應(yīng)使用解決方案的名稱，每個(gè)項(xiàng)目應(yīng)設(shè)置一個(gè)二級(jí)命名空間，并以項(xiàng)目名命名。如下圖：SDP為解決方案（Solution）的名稱，則SDP為頂級(jí)命名空間；SDP.BF為項(xiàng)目名稱（Assembly），則SDP.BF項(xiàng)目下的命名空間為：SDP.BF.ClassName 回目錄四、文件命名規(guī)范1. 文件命名原則是更容易區(qū)分不同的文件類型，在文件名前增加三字符的前綴，前綴字母一律為小寫(xiě)例如：一個(gè)窗體文件可以增加frm前綴，frmForm1.cs所有的前綴列表請(qǐng)參考本小節(jié)末尾的表格!2. 文件主體名必須用名詞或動(dòng)名詞，且主體名必須是單詞首字大寫(xiě)的方式表示例如：銷貨單的窗體可以命名為frmInvoice.cs，一張銷貨單批次作廢的窗體可以命名為frmCancelInvoice.cs3. 文件名必須采用在不影響原意表達(dá)時(shí)盡量采用單詞縮寫(xiě)的形式命名，以達(dá)到文件名的簡(jiǎn)潔明了的命名目的例如：應(yīng)收帳款批次轉(zhuǎn)憑證窗體的完整窗體名為frmTransferAccountsReceivable.cs，這時(shí)的窗體文件名太長(zhǎng)，可以采用簡(jiǎn)寫(xiě)的方式，應(yīng)收帳款專業(yè)簡(jiǎn)寫(xiě)為AR，我們可以采取這種公認(rèn)的或?qū)I(yè)的簡(jiǎn)寫(xiě)名詞命名，最后可以命名為frmTransAR非標(biāo)準(zhǔn)縮寫(xiě)單詞采用去掉元音字母或半元音字母的方式命名，重復(fù)字只取一個(gè)。例如：Button：btn,省圖掉u,o和t。4. 文件名要和類名匹配例如，對(duì)于類HelloWorld, 相應(yīng)的文件名應(yīng)為 HelloWorld.cs (或, HelloWorld.vb)5. 文件類型前綴一覽表（/表示暫無(wú)前綴）Win Form擴(kuò)展名Extension File Name描述Description前綴Prefix.cs窗體文件frm.cs類文件/Web Form擴(kuò)展名Extension File Name描述Description前綴Prefix.aspx/.ascxWeb用戶自定義控件wuc 回目錄五、控件命名規(guī)范1. C#編碼時(shí)，為了更直觀地遍歷整個(gè)窗體的控件，通常的作法是給每一種類型的控件的名稱前增加統(tǒng)一的前綴。前綴字符采用三個(gè)小寫(xiě)字母的形式表示（一般常用的控件三個(gè)字母都可以滿足，也有一些控件無(wú)法更好地用三個(gè)字母縮寫(xiě)，詳見(jiàn)下面的表格。）例如：一個(gè)開(kāi)始處理的按鈕可以命名為：btnBeginProc2. 控件主體名稱采用名詞或動(dòng)名詞的形式命名例如：1. 一個(gè)單號(hào)的標(biāo)簽：lblDocNo2. 一個(gè)開(kāi)始處理的按鈕：btnBeginProc3. 控件主體名采用單詞首字大寫(xiě)的形式命名例如：一個(gè)產(chǎn)生應(yīng)收帳款的按鈕可以命名為：btnMakeAR 回目錄5.1 Win Form內(nèi)部控件命名規(guī)范控件類型Control Type前綴Prefix例子ExampleLabellbllblStartSyncLabelLinklbkButtonbtnTextBoxtxtMainMenumnuCheckBoxchkRadioButtonrdoGroupBoxgrpPictureBoxpicPanelpanDataGridgrdListBoxlstCheckedListBoxchklstCombocboListViewlstvTreeViewtrvTabControltabDateTimerPickerdtpMonthCalendarcldHScrollBarhsbVScrollBarvsbTimertmrSplittersplDomainUpDowndupNumericUpDownnupTrackBartrkProgressBarpgrRichTextBoxrtxtImageListimglstHelpProviderhlpToolTiptlpContextMenumnuToolBartlbStatusBarstaNotifyIconntiOpenFileDialogofdSaveFileDialogsfdFolderBrowserDialogfbdFontDialogfdgColorDialogcdgPrintDialogpdgPrintPreviewDialogppdPrintPreviewControlppcErrorProvidererpPrintDocumentprdPageSetupDialogpsdCrystalReportViewercrv 回目錄5.2 Web Form內(nèi)部控件命名規(guī)范控件類型Control Type前綴Prefix例子ExampleLabellbllblTipTextBoxtxttxtNameButtonbtnbtnOKLinkButtonlbtnImageButtonibtnHyperLinkhlkDropDownListddlListBoxlstDataGridgrdDataListdlstRepeaterrepCheckBoxchkCheckBoxListchklstRadioButtonListrdolstRadioButtonrdoImageimgPanelpanPlaceHolderplhCalendarcldAdRotatoradrTabletblRequireFieldValidatorrfvCompareValidatorcpvRangeValidatorrgvRegularExpressionValidatorrevCustomValidatorcstvValidationSummaryvlsXmlxmlLitteralltlCrystalReportViewercrv 回目錄5.3 C#數(shù)據(jù)組件命名規(guī)范數(shù)據(jù)庫(kù)對(duì)象Data Object前綴Prefix例子ExampleDataSetDsdsDeptDataTabledtdtDeptDataTableCollectiondtcdtcDeptDataViewdvdvDeptDataRowdrdrDeptDataRowCollectiondrcdrcDeptDataColumndcdcFieldDataColumnCollectiondccdccDeptDataRowViewdrvdrvDeptOleDb Data ProviderOleDbDataAdapteroleadpOleDbConnectionoleconnOleDbCommandolecmdSql Server Data ProviderSqlDataAdaptersqladpSqlConnectionsqlconnSqlCommandsqlcmdOdbc Data ProviderOdbcDataAdapterodbcadpOdbcConnectionodbcconnOdbcCommandodbccmdOracle Data ProviderOracleDataAdapteroraadpOracleConnectionoraconnOracleCommandoracmd 回目錄5.4 C#菜單命名規(guī)范應(yīng)用程序頻繁使用許多菜單控件，對(duì)于這些控件具備一組唯一的命名約定很實(shí)用。除了最前面 mnu 標(biāo)記以外，菜單控件的前綴應(yīng)該被擴(kuò)展：對(duì)每一級(jí)嵌套增加一個(gè)附加前綴，將最終的菜單的標(biāo)題放在名稱字符串的最后。下表列出了一些例子。菜單標(biāo)題序列菜單處理器名稱File OpenmnuFileOpenFile Send EmailmnuFileSendEmailFile Send Fax mnuFileSendFaxFormat CharactermnuFormatCharacterHelp ContentsmnuHelpContents當(dāng)使用這種命名約定時(shí)，一個(gè)特定的菜單組的所有成員一個(gè)接一個(gè)地列在 .net 的“屬性”窗口中。而且，菜單控件的名字清楚地表示出它們所屬的菜單項(xiàng)。 回目錄六、變/常量命名規(guī)范6.1變量范圍前綴1. 為了更好地區(qū)分變量的有效范圍，例如Class級(jí)變量，在定義變量名時(shí)用小寫(xiě)字母前綴區(qū)分。2. 此約定同樣適用于常量的命名。3. 常量名必須大寫(xiě)。 回目錄6.2變量類型前綴1. 定義變量時(shí)根據(jù)不同的變量類型增加特定的變量類型前綴，一般為小寫(xiě)的三個(gè)字母表示2. 變量主體名與控件主體名和窗體主體名的命名方式一致，采用單詞首字大寫(xiě)的方式命名數(shù)據(jù)類型Data typeCLR類型CLR Type前綴Prefix例子ExampleboolSystem.BooleanblnbyteSystem.BytebytsbyteSystem.SBytesbytcharSystem.CharchrdecimalSystem.DecimaldecdoubleSystem.DoubledblfloatSystem.SinglefltintSystem.Int32intuintSystem.UInt32uintlongSystem.Int64lngulongSystem.UInt64ulngshortSystem.Int16shtushortSystem.UInt16ushtstringSystem.StringstrdatetimeSystem.DateTimedtmobjectSystem.Objectobj枚舉enuStructurestru綜上所述，變量命名格式為：特殊類型前導(dǎo)字：前導(dǎo)字?jǐn)?shù)據(jù)型態(tài)a任何型態(tài)的數(shù)組(不區(qū)分為幾維的數(shù)組)mClass級(jí)變量前綴I所有接口聲明及變量都應(yīng)以大寫(xiě)I作為前綴E枚舉聲明增加E前綴有效變量定義的例子：int aintCounters = new int10;(表示一個(gè)方法級(jí)的整型計(jì)數(shù)器數(shù)組)int maintCounters = new int10;(表示一個(gè)class級(jí)的整型計(jì)數(shù)器數(shù)組) 回目錄七、方法命名規(guī)范1. 方法名的主體應(yīng)該使用大小寫(xiě)混合形式，并且應(yīng)該足夠長(zhǎng)以描述它的作用。而且，方法名應(yīng)該以一個(gè)動(dòng)詞起首，如 InitNameArray 或 CloseDialog。2. 對(duì)于頻繁使用的或長(zhǎng)的項(xiàng)，推薦使用標(biāo)準(zhǔn)縮略語(yǔ)以使名稱的長(zhǎng)度合理化。一般來(lái)說(shuō)，超過(guò) 32 個(gè)字符的變量名在 VGA 顯示器上讀起來(lái)就困難了。3. 當(dāng)使用縮略語(yǔ)時(shí)，要確保它們?cè)谡麄€(gè)應(yīng)用程序中的一致性。在一個(gè)工程中，如果一會(huì)兒使用 Cnt， 一會(huì)兒使用 Count，將導(dǎo)致不必要的混淆。 回目錄八、代碼注釋規(guī)范8.1代碼注釋約定1. 所有的方法和函數(shù)都應(yīng)該以描述這段代碼的功能的一段簡(jiǎn)明注釋開(kāi)始（方法是干什么）。這種描述不應(yīng)該包括執(zhí)行過(guò)程細(xì)節(jié)（它是怎么做的），因?yàn)檫@常常是隨時(shí)間而變的，而且這種描述會(huì)導(dǎo)致不必要的注釋維護(hù)工作，甚至更糟成為錯(cuò)誤的注釋。代碼本身和必要的嵌入注釋將描述實(shí)現(xiàn)方法。2. 當(dāng)參數(shù)的功能不明顯且當(dāng)過(guò)程希望參數(shù)在一個(gè)特定的范圍內(nèi)時(shí)，也應(yīng)描述傳遞給過(guò)程的參數(shù)。被過(guò)程改變的函數(shù)返回值和全局變量，特別是通過(guò)引用參數(shù)的那些，也必須在每個(gè)過(guò)程的起始處描述它們。 回目錄8.2模塊頭部注釋規(guī)范以一個(gè)物理文件為單元的都需要，例如C#中包括 cs 檔用于每個(gè)模塊開(kāi)頭的說(shuō)明，主要包括：（粗體字為必需部分，斜體字為可選部分）1. 文件名稱(File Name)：此文件的名稱2. 功能描述(Description)：此模塊的功能描述與大概流程說(shuō)明3. 數(shù)據(jù)表(Tables)：所用到的數(shù)據(jù)表，視圖，存儲(chǔ)過(guò)程的說(shuō)明，如關(guān)系比較復(fù)雜，則應(yīng)說(shuō)明哪些是可擦寫(xiě)的，哪些表為只讀的。4. 作者(Author)：5. 日期(Create Date)：6. 參考文檔(Reference)：該檔所對(duì)應(yīng)的分析文檔，設(shè)計(jì)文檔。7. 引用(Using)開(kāi)發(fā)的系統(tǒng)中引用其它系統(tǒng)的Dll、對(duì)象時(shí)，要列出其對(duì)應(yīng)的出處，是否與系統(tǒng)有關(guān)不清楚的可以不寫(xiě)，以方便制作安裝檔。8. 修改記錄(Revision History)：若檔案的所有者改變，則需要有修改人員的名字、修改日期及修改理由。R1:修改作者:修改日期：修改理由:R2:修改作者:修改日期：修改理由:R3:R10R1009. 分割符： (前后都要)例圖如下： 回目錄8.3方法注釋規(guī)范注意事項(xiàng)：1. 事件不需要頭注解，但包含復(fù)雜處理時(shí)（如：循環(huán)/數(shù)據(jù)庫(kù)操作/復(fù)雜邏輯等），應(yīng)分割成單一處理函數(shù)，事件再調(diào)用函數(shù)。2. 所有的方法必須在其定義前增加方法注釋3. 方法注釋采用 / 形式自動(dòng)產(chǎn)生XML標(biāo)簽格式的注釋/ / / / / 標(biāo)記說(shuō)明備注提供了一種將說(shuō)明中的文本標(biāo)記為代碼的方法提供了一種將多行指示為代碼的方法可以指定使用方法或其他庫(kù)成員的示例。一般情況下，這將涉及到 標(biāo)記的使用。對(duì)可從當(dāng)前編譯環(huán)境中獲取的異常的引用。得以引用描述源代碼中類型和成員的另一文件中的注釋。用于定義表或定義列表中的標(biāo)題行。用于諸如、 或 等標(biāo)記內(nèi)，使您得以將結(jié)構(gòu)添加到文本中。應(yīng)當(dāng)用于方法聲明的注釋中，以描述方法的一個(gè)參數(shù)。提供了一種指示詞為參數(shù)的方法。得以將成員的訪問(wèn)記入文檔。用于添加有關(guān)某個(gè)類型的信息，從而補(bǔ)充由 所指定的信息。應(yīng)當(dāng)用于方法聲明的注釋，以描述返回值。得以從文本內(nèi)指定鏈接。對(duì)可以通過(guò)當(dāng)前編譯環(huán)境進(jìn)行調(diào)用的成員或字段的引用。應(yīng)當(dāng)用于描述類型或類型成員。得以描述屬性。上述表格具體說(shuō)明見(jiàn) “Microsoft Visual Studio .NET 2003 文檔“ 之 “Visual Studio .NETVisual Basic 和 Visual C#參考Visual C# 語(yǔ)言C# 程序員參考C# 語(yǔ)言功能XML 文檔建議的文檔注釋標(biāo)記” 的目錄。例圖如下：4. 在公用類庫(kù)中的公用方法需要在一般方法的注釋后添加作者、日期及修改記錄信息，統(tǒng)一采用XML標(biāo)簽的格式加注，標(biāo)簽如下： 作者 建立日期 修必記錄修改作者修改日期修改理由修改作者修改日期修改理由修改作者修改日期修改理由 最后修改日期5. 一個(gè)代碼文件如果是由一人編寫(xiě)，則此代碼文件中的方法無(wú)需作者信息，非代碼文件作者在此文件中添加方法時(shí)必須要添加作者、日期等注釋，格式參考8.4。6. 修改任何方法，必須要添加修改記錄的注釋，格式參考8.4。 回目錄8.4代碼行注釋規(guī)范1. 如果處理某一個(gè)功能需要很多行代碼實(shí)現(xiàn)，并且有很多邏輯結(jié)構(gòu)塊，類似此種代碼應(yīng)該在代碼開(kāi)始前添加注釋，說(shuō)明此塊代碼的處理思路及注意事項(xiàng)等2. 注釋從新行增加，與代碼開(kāi)始處左對(duì)齊3. 雙斜線與注釋之間以空格分開(kāi)例如： 回目錄8.5變量注釋規(guī)范1. 定義變量時(shí)需添加變量注釋，用以說(shuō)明變量的用途2. class級(jí)變量應(yīng)以三條斜線的形式注釋3. 方法級(jí)的變量注釋可以放在變量聲明語(yǔ)句的后面，與前后行變量聲明的注釋左對(duì)齊，注釋與代碼間以Tab隔開(kāi)。例如： 回目錄九、其它規(guī)范9.1編程風(fēng)格1. 為了保持更好的閱讀習(xí)慣，請(qǐng)不要把多個(gè)變量聲明寫(xiě)在一行中，即一行只聲明一個(gè)變量。例如：String strTest1,strTest2;應(yīng)寫(xiě)成：String strTest1;String strTest2;2 避免方法中有超過(guò)5個(gè)參數(shù)的情況。如果超過(guò)了，則應(yīng)使用 struct 來(lái)傳遞多個(gè)參數(shù)。3 為了更容易閱讀，代碼行請(qǐng)不要太長(zhǎng)，最好的寬度是屏幕寬度（根據(jù)不同的顯示分辯率其可見(jiàn)寬度也不同）。請(qǐng)不要超過(guò)您正在使用的屏幕寬度。（每行代碼不要超過(guò)80個(gè)字符。）4 除非在不完全的switch語(yǔ)句中否則不要使用goto語(yǔ)句。注：原則上不應(yīng)使用goto語(yǔ)句，除非在能夠大大減輕編碼的復(fù)雜性，并不影響可讀性的前提下才允許使用。5 在switch語(yǔ)句中總是要有default子句來(lái)顯示信息6 代碼縮進(jìn)1. 一致的代碼縮進(jìn)風(fēng)格，有利于代碼的結(jié)構(gòu)層次的表達(dá)，使代碼更容易閱讀和傳閱2. 代碼縮進(jìn)請(qǐng)使用“”鍵實(shí)現(xiàn)，講不要使用空格，為保證在不同的機(jī)器上使代碼縮進(jìn)保持一致，特此規(guī)定C的TAB鍵寬度為個(gè)字符，設(shè)定界面如下(C# ToolsOption)：7 界面排版8 方法參數(shù)多于8個(gè)時(shí)采用結(jié)構(gòu)體或類方式傳遞9 操作符/運(yùn)算符左右空一個(gè)半角空格10 所有塊的號(hào)分別放置一行，并嵌套對(duì)齊，不要放在同一行上 回目錄9.2資源釋放所有外部資源都必須顯式釋放。例如：數(shù)據(jù)庫(kù)連接對(duì)象、IO對(duì)象等。public void Dispose()/ 如果事務(wù)開(kāi)啟過(guò)，則釋放事務(wù)對(duì)象if ( this.IDbTrans != null)this.IDbTrans.Dispose();/ 如果連接已經(jīng)打開(kāi)，則關(guān)閉連接并釋放資源if ( this.IDbConn.State = ConnectionState.Open )this.IDbConn.Close();this.IDbConn.Dispose(); 回目錄9.3錯(cuò)誤處理：1. 不要“捕捉了異常卻什么也不做“。如果隱藏了一個(gè)異常，你將永遠(yuǎn)不知道異常到底發(fā)生了沒(méi)有。 2. 發(fā)生異常時(shí)，給出友好的消息給用戶，但要精確記錄錯(cuò)誤的所有可能細(xì)節(jié)，包括發(fā)生的時(shí)間，和相關(guān)方法，類名等。 3. 只捕捉特定的異常，而不是一般的異常。正確的做法：void ReadFromFile ( string fileName )try/ read from file.catch (FileIOException ex)/ log error./ re-throw exception depending on your case.throw;不好： void ReadFromFile ( string fileName )