規則：編程時必須遵守的約定。
建議：編程時必須加以考慮的約定。
1 代碼格式
【規則 1-1】全部代碼使用TAB鍵縮進。
【規則 1-2】代碼行的長度小於120個字符。
【規則 1-3】“{”放在行首，“}”新起一行也在行首。
【規則 1-4】不要在相關的一組類或者是一個模塊中使用不同的代碼格式。
【規則 1-5】成員按照一定的順序，並且使用#region分組。
2 命名規範
【規則 2-1】使用英文命名標識符。
【規則 2-2】使用Pascal大小寫和Camel大小寫命名標識符。
l Pascal大小寫是每個單詞的首字母大寫。例如：BackColor。
l Camel大小寫是第一個單詞的首字母小寫，其餘單詞的首字母大寫。例如：backColor。
【規則 2-3】不使用匈牙利命名法。
〖建議 2-1〗注意縮寫的使用。
l 如果不是絕對必須，儘量避免使用短的名稱。
l 如果標識符中單詞的縮寫只能縮短一兩個字符則使用單詞的完全拼寫。
l 所有單詞的縮寫規則應當一致。
〖建議 2-2〗標識符應當直觀且可以拼讀，可望文知意，不必進行“解碼”。
【規則 2-4】DLL Assembly命名使用它所包含的命名空間。
【規則 2-5】文件名和所包含的類名相同。
【規則 2-6】所有布爾型變量的命名能夠直接從名稱上看出爲真的條件。
【規則 2-7】程序中不要出現僅靠大小寫區分的相似的標識符。
3 註釋
【規則 3-1】每個CS文件都包含文件頭，並且使用#region分組。
【規則 3-2】文件頭說明版權、文件名和文件的作者，創建時間，變更記錄。
【規則 3-4】註釋使用//，不使用//-----------------或者//************。
〖建議 3-1〗所有的註釋都應該用英文或者中文，同一段註釋不要混用兩種語言。
【規則 3-5】使用XML標記說明類型和成員。
【規則 3-6】代碼變更需要將舊代碼註釋，並且說明變更原因，變更作者和變更時間。
4 變量使用
〖建議 4-1〗在接近使用變量的地方定義和初始化變量。
〖建議 4-2〗如果可能，在定義的同時初始化變量。
【規則 4-1】一個定義語句只定義一個變量，以便於寫註釋。
〖建議 4-3〗設置引用爲null告訴GC對象不再需要。
【規則 4-2】不使用“魔術數字”。
|
if (custTypeId == 1) //錯誤
int ORG_CUST_TYPE_ID = 1; if (custTypeId == ORG_CUST_TYPE_ID) //正確 |
【規則 4-3】使用StringBuilder或者String.Format構造字符串。
5 控制流
【規則 5-1】不要在for循環內部改變循環變量的值。
〖建議 5-1〗if、for、while、do等語句自佔一行，執行語句不得緊跟其後。不論執行語句有多少都要加{}。這樣可以防止書寫失誤。
〖建議 5-2〗在switch語句中總是要有default子句。建議使用斷言。
|
int number = SomeMethod(); switch(number) { case 1: Trace.WriteLine("Case 1:"); break; case 2: Trace.WriteLine("Case 2:"); break; default : Debug.Assert(false); break; } |
6 異常
【規則 6-1】僅在例外情況下拋出異常。
【規則 6-1】僅在需要指定異常時re-throw異常。
【規則 6-1】使用<exception>標記顯式的列出方法和屬性可能拋出的異常。
【規則 6-1】在異常拋出時需要記錄日誌。
【規則 6-1】使用.NetFramework已經提供異常。
【規則 6-1】拋出附帶信息的異常。
【規則 6-1】拋出最合適的異常。
【規則 6-1】只捕捉在文檔顯式說明的異常。
7 [C1] SQL編碼規範
【規則 7-1】SQL語句全部大寫。
【規則 7-2】連接符OR、IN、AND、以及=、<=、>=等前後加上一個空格。
【規則 7-3】對較爲複雜的SQL語句加上註釋，說明算法、功能。
【規則 7-4】WHERE子句的每個條件佔一行，並且以保留字開始。
【規則 7-5】多表連接時，使用表的別名來引用列。
【規則 7-6】使用明確的列代替SELECT *。
|
SELECT A.ID, A.NAME, B.ID B_ID, B.NAME B_NAME FROM CLASS A, SCHOOL B WHERE A.SCHOOL_ID = B.ID AND A.STATE = ‘10A’ AND B.STATE = ‘10A’ |
8 附錄
8.1 代碼範例
|
#region Copyright Ztesoft 2004 // // All rights are reserved. Reproduction or transmission in whole or in part， in // any form or by any means， electronic， mechanical or otherwise， is prohibited // without the prior written consent of the copyright owner. // // Filename: PatientList.cs // Author: TangXing // CreateDate: 2004-08-25 // // Modified By TangXing // ChangedDate: 2004-08-27 // Reason: BugId=555 // #endregion
using System; using System.Collections;
namespace Ztesoft.BS.PatientList { /// <summary> /// Objects of this class manage a list of patients and their history. /// </summary> /// <remarks> /// This class relies on the <see cref="Patient"/> class. /// </remarks> /// <seealso cref="Patient"/> public class PatientList {
/// <summary>Holds a list of Patient objects.</summary> private ArrayList list = new ArrayList();
/// <summary>Maximum number of patients supported.</summary> private const uint maxPatients = 100;
/// <summary>Defines the gender of the patient.</summary> public enum Gender { /// <summary>The patient is a male.</summary> Male, /// <summary>The patient is a female.</summary> Female, /// <summary>A phantom object used for testing</summary> Phantom }
/// <overloads> /// Adds new patients to the list. /// </overloads> /// <summary> /// Adds a new patient to the end of the current list. /// </summary> /// <remarks> /// The actual data of the Patient object is not checked or changed. /// </remarks> /// <exception cref="NullReferenceException"> /// The <paramref name="patient"/> argument was null. /// </exception> /// <param name="patient">The patient object to add.</param> /// <returns> /// <b>true</b> if the patient was added, </b>false</b> if the list is /// full. /// </returns> public bool Add(Patient patient) { if (null == patient) { throw new NullReferenceException( "patient argument must not be null"); }
bool success = false;
if (list.Count < maxPatients) { list.Add(patient); success = true;
// Raise the event and pass the new patient to the event // handler. Added(this, new PatientAddedEventArgs(patient)); }
return success; }
/// <summary> /// Adds a new patient at the specified index in the list. /// </summary> /// <remarks> /// The following rules apply. /// <list type="bullet"> /// <item> /// The actual data of the Patient object is not checked or /// changed. /// </item> /// <item> /// The item at the specified <paramref name="index"/> will be /// moved one place up. /// </item> /// </list> /// </remarks> /// <exception cref="NullReferenceException"> /// The <paramref name="patient"/> argument was null. /// </exception> /// <exception cref="IndexOutOfBounds"> /// The index was invalid. /// </exception> /// <param name="patient">The patient object to add.</param> /// <param name="index">The index to use for inserting.</param> /// <returns> /// true if the patient was added, false if the list is full. /// </returns> public bool Add(Patient patient, int index) { // Code left out for brevity. }
/// <summary> /// Searches the contents of the list for patients of a certain gender. /// </summary> /// <param name="gender">The gender to use during matching.</param> /// <returns> /// Returns an array of <see cref="Patient"/> objects or <b>null</b> if /// no items have been found. /// </returns> public Patient[] GetPatientsByGender(Gender gender) { // Code left out for brevity. }
/// <summary> /// Gets a value indicating the size of the list. /// </summary> /// <value> /// The current number of entries in the list. /// </value> public uint Count { get { return list.Count; } }
/// <summary> /// Occurs when a new patient is added to the list. /// </summary> /// <remarks> /// This event typically occurs when <see cref="Add"/> has successfully /// added a new patient. The data is passed through an instance of the /// <see cref=”PatientAddedEventArgs”/> class. /// </remarks> public event EventHandler Added; }
/// <summary> /// Holds the data associated with the <see cref="Added"/> event. /// </summary> public class PatientAddedEventArgs : EventArgs { public PatientAddedEventArgs(Patient newPatient) { // Code left out for brevity }
/// Remainder of the class left out for brevity... } }
|
8.2 標識符大小寫
|
標示符 |
大小寫 |
示例/說明 |
|
namespace |
Pascal |
Ztesoft.BS.Model，以公司名.模塊名[.功能[.設計]]命名 |
|
class |
Pascal |
AppDomain |
|
enum |
Pascal |
ErrorLevel，enum內的值按照常量來編碼 |
|
delegate |
Pascal |
MouseEventHandler，以Handler爲後綴 |
|
event |
Pascal |
ValueChanged |
|
Exception |
Pascal |
Exception爲後綴 |
|
常量 |
全部大寫 |
RED_VALUE |
|
接口 |
Pascal |
IDisposable，總是以I開頭 |
|
方法 |
Pascal |
ToString |
|
參數 |
camel |
typeName |
|
屬性(Property) |
Pascal |
BackColor |
|
受保護的實例字段(Field) |
camel |
backColor 注意：很少使用。屬性優於使用受保護的實例字段。 |
|
公用實例字段(Field) |
Pascal |
BackColor 注意：很少使用。屬性優於使用公用實例字段。 |
|
Attribute |
Pascal |
XmlElementAttribute，最後要以Attribute結束 |
Pascal 大小寫
將標識符的首字母和後面連接的每個單詞的首字母都大寫。可以對三字符或更多字符的標識符使用 Pascal 大小寫。例如：
BackColor
Camel 大小寫
標識符的首字母小寫，而每個後面連接的單詞的首字母都大寫。例如：
backColor
大寫
標識符中的所有字母都大寫。僅對於由兩個或者更少字母組成的標識符使用該約定。例如：
System.IO
System.Web.UI
8.3 使用XML標記說明類型和成員
|
SECTION TAGS |
描述 |
位置 |
|
<summary> |
簡短描述 |
type or member |
|
<remarks> |
描述前提條件和其他附加信息 |
type or member |
|
<param> |
描述method的參數 |
method |
|
<return> |
描述method的返回值 |
method |
|
<exception> |
方法或者屬性可能拋出的異常列表 |
method，event or property |
|
<value> |
描述property能夠接受的或者返回的數據類型 |
property |
|
<example> |
type或者member的範例（代碼或者文本） |
type or |
|
<seealso> |
增加一個實體到See Also段 |
type or member |
|
<overload> |
爲method的overload提供一個摘要 |
在重載列表中的第一個方法 |
|
MARKUP TAGS |
描述 |
|
<code> |
對代碼範例改變縮進策略 |
|
<c> |
改變字體爲等寬字體 |
|
<para> |
創建一個新段落 |
|
<list> |
創建一個列表 |
|
<b> |
粗體 |
|
<i> |
斜體 |
8.4 命名空間約定
|
命名空間 |
說明 |
備註 |
|
Ztesoft.BS |
前綴 |
|
|
Ztesoft.BS.Commons |
前後臺公用 |
|
|
Ztesoft.BS.Commons.Logging |
日誌 |
|
|
Ztesfot.BS.Commons. XmlWebFuncHelper |
XML自動序列化 |
|
|
Ztesoft.BS.Exceptions |
全局異常類 |
|
|
Ztesoft.BS.Web |
Web應用 |
|
|
Ztesoft.BS.PPM
|
產品管理後臺 |
|
|
Ztesoft.BS.CM |
客戶管理後臺 |
|
|
Ztesoft.BS.CCM |
客服管理後臺 |
|
|
Ztesoft.BS.DAO
|
後臺DAO公用
|
|
|
Ztesoft.BS.Model
|
後臺DTO公用
|
|
|
後臺模塊舉例 |
||
|
Ztesoft.BS.CCM.OrderManagement |
訂單管理 |
應用程序異常、常量定義也放在該命名空間 |
|
Ztesoft.BS.CCM.OrderManagement.BL |
訂單管理業務邏輯層 |
|
|
Ztesoft.BS.CCM.OrderManagement.DAL |
訂單管理數據訪問層 |
|
|
Ztesoft.BS.CCM.OrderManagement.SA |
訂單管理服務代理層 |
|
8.5 類名後綴約定
|
類名 |
說明 |
備註 |
|
XxxxDto |
數據傳輸對象 |
|
|
XxxDAOFactory |
DAO工廠 |
|
|
IXxxxDAO |
DAO接口 |
|
|
XxxxDAOOracle/XxxxDAOInfomix |
DAO的數據庫實現 |
|
|
XxxxServiceAgent |
服務代理 |
|
|
XxxxManager |
業務邏輯 |
|
|
XxxxService |
服務接口 |
|
|
XxxxFacade |
業務正面 |
|
|
BSXxxxException |
應用程序異常 |
|
8.6 數據傳輸對象（DTO）編碼約定
1. DTO的類名使用Dto後綴
2. 數據庫中每一張表對應一個DTO
3. DTO中數據類型除String外，都使用Ztesoft.BS.Commons.Model.BaseType命名空間中的Wrapper類
|
數據庫類型 |
.Net數據類型 |
默認值 |
備註 |
|
varchar/char |
String |
null |
|
|
number(m，n) |
BaseType.Double |
null |
|
|
number(n) |
BaseType.Long |
null |
|
|
Date |
BaseType.DateTime |
null |
|
4. DTO中包含DTO，屬性名使用DTO完整類型；DTO包含DTO數組，屬性名使用DTO完整類名+List後綴
AcctDto包含CustDto
|
private CustDto custDto; public CustDto CustDto { get {return custDto;} set {this.custDto = value;} } |
CustDto包含多個AcctDto
|
private AcctDto[] acctDtoList; public AcctDto[] AcctDtoList { get {return acctDtoList;} set {this. acctDtoList = value;} } |