應用程序設計/命名及編碼規範方案
架構規範
總體設計
.NET web forms 應用程序的架構應遵循Microsoft建議的架構方案. 根據項目規模不同, 適當取捨各個基本層次. 將系統劃分爲多層的目的在於簡化隔離各個子系統內部邏輯. 大體上應按照以下規則創建:
應至少包含表示層與業務
一般應將應用程序劃分爲: 表示層, 業務邏輯層, 數據訪問三層.
如果業務過程較複雜, 應增加業務規則層
應爲業務過程中的基本業務對象實現數據實體(一般是DataSet擴充子類)
應單一地使用存儲過程操作數據庫
如果需要與業務無關的基礎組件(全局參數配置, 異常處理, 日誌), 應包含應用程序框架層(System Framework)
如果包含Custom Controls, 應單獨作爲一項project.
上圖是Visual Sudio.NET 所提供的樣版應用Duwamish 7.0的系統架構. 其中參與關鍵數據流程的是web, business façade, business rules, data access. 上圖形象說明了各層之間調用關係.
表示層(ASP.NET)設計
在整個解決方案中, 只有表示層含有ASPX文件, 即ASP.NET技術. 表示層的任務爲將數據以一定格式展示給用戶, 而且可以接受用戶輸入的數據, 處理用戶的操作. 表示層由web forms頁, user control, 和code behide組成, 一般還包含所需要的其他資源文件. 設計及架構上應遵循以下原則:
1. 爲了最大限度重用頁面構圖設計, 應將頁面的主要公共元素(主菜單, 頁眉頁腳)構建爲ASCX.
2. 應將主要邏輯模塊建立在同一個ASCX中。例如用戶註冊的過程. 由獨立的、嵌入到頁面中的、模塊來處理該邏輯。這樣做的好處是隔離呈現邏輯與業務邏輯。
3. ASPX頁面僅僅是少量基本HTML, 表現基本頁面構圖。Code Behind僅僅操作所承載ASCX的顯示與隱藏。 不包含業務邏輯
4. 應從System.Web.UI.Controls.WebControls.Page與 System.Web.UI.Controls.WebControls.UserControl擴展出派生類。本層下所有ASPX與ASCX均擴展該類。基類應包含安全信息，用戶狀態等基本信息。
5. ASPX應可捕獲所承載控件的用戶事件。 用戶事件一般代表ASCX生命週期的各個階段。例如控件初始化，操作取消，操作完成，操作中止。
6. 呈現數據的集合時，應儘量使用Repeater.
數據實體設計
數據實體是系統所處理的核心業務對象。拿一個電子商務應用來說，核心業務對象就是商品，供貨方，顧客，訂單。數據實體一般爲DataSet. 每個DataSet都是被強制定義了表，列以及關係和約束的內存數據庫。 表結構的定義是可以和數據庫中實際數據有差別的。各個層之間傳送的數據就是單純的DataSet。這樣可以是各層對外開發的接口完全統一。 例如當用戶要求查詢所有某類別的商品時，數據層可以將結果填充進事先設計好的實體中。
業務層設計
業務層直接服務於表示層。爲表示層提供所需數據。處理表示層的操作需求。實際上，業務層所擔當的角色是表示層與數據訪問層的中介。 將表示層的需求解析爲數據層的數據操作。這應用了FACADE設計模式。即爲子系統提供一個統一的接口以簡化操作。在實際的設計中。 一般將業務層的類設計爲各個核心子系統的各項操作的中心。 可降低系統層次之間的耦合度。 提高靈活性。
數據層設計
數據庫直接對數據庫操作。一般不應該包含任何業務邏輯。好的數據層設計應該是僅包含讀寫刪改等基本操作。提供業務層所需要的數據。
命名規範
大小寫形式
項目進行前應安排專門人員制定詞彙表。開發成員選用詞彙時應按照詞彙表選用準確的詞彙. 以達到風格統一的目的.
以下規則按照MSDN 推薦的樣式表示下列標識符:
|
Identifier |
Case |
Example |
|
Class |
Pascal |
AppDomain |
|
Enum type |
Pascal |
ErrorLevel |
|
Enum values |
Pascal |
FatalError |
|
Event |
Pascal |
ValueChange |
|
Exception class |
Pascal |
WebException Note Always ends with the suffix Exception. |
|
Read-only Static field |
Pascal |
RedValue |
|
Interface |
Pascal |
IDisposable Note Always begins with the prefix I. |
|
Method |
Pascal |
ToString |
|
Namespace |
Pascal |
System.Drawing |
|
Parameter |
Camel |
typeName |
|
Property |
Pascal |
BackColor |
|
Protected instance field |
Camel |
redValue Note Rarely used. A property is preferable to using a protected instance field. |
|
Public instance field |
Pascal |
RedValue Note Rarely used. A property is preferable to using a public instance field. |
大小寫敏感設置
由於.NET平臺是跨語言操作, 對於大小寫敏感的語言和大小寫不敏感的語言都要求適用, 所以絕對不能使用僅依靠大小寫識別的標誌符.
縮寫形式
1. 不允許使用任何對於英文單詞的簡寫或者縮寫.例如將 GetWindow寫成 GetWin.
2. 不允許使用省去元音字母的縮寫形式.例如將Message寫成Msg.
3. 不允許使用尚未被廣泛採用的只用首字母的縮寫詞.
4. 使用約定俗稱的首字母縮寫來代替較長的名稱. 例如 GetHtml.
5. 縮寫詞應當作一個單詞使用, 即採用首字母大寫其他字母小寫的形式. 例如 SqlServer.
6. 如果縮寫詞只有兩位字符. 應全部大寫. 例如 System.Web.UI.
應遵守的通用規則
1. 必須使用拼寫正確的英文單詞。不允許使用漢語拼音或者其他任何形式的縮寫。
2. 詞彙必須完整。不允許使用任何簡寫形式。 例如不允許將Message寫成Msg.
3. 如果名字代表複數意義，應使用其正確的複數形式。
4. 約定俗成的字母縮寫，可作爲一個單詞使用。
5. 應儘量將標誌符的意義描述清楚。即使用一個以上的單詞來表示一項內容。
規避詞彙
避免使用.NET namespace佔用的詞彙. 避免使用與關鍵字衝突的詞彙:
關鍵字列表:
AddHandler AddressOf Alias And Ansi
As Assembly Auto Base Boolean
ByRef Byte ByVal Call Case
Catch CBool CByte CChar CDate
CDec CDbl Char CInt Class
CLng CObj Const CShort CSng
CStr CType Date Decimal Declare
Default Delegate Dim Do Double
Each Else ElseIf End Enum
Erase Error Event Exit ExternalSource
False Finalize Finally Float For
Friend Function Get GetType Goto
Handles If Implements Imports In
Inherits Integer Interface Is Let
Lib Like Long Loop Me
Mod Module MustInherit MustOverride MyBase
MyClass Namespace New Next Not
Nothing NotInheritable NotOverridable Object On
Option Optional Or Overloads Overridable
Overrides ParamArray Preserve Private Property
Protected Public RaiseEvent ReadOnly ReDim
Region REM RemoveHandler Resume Return
Select Set Shadows Shared Short
Single Static Step Stop String
Structure Sub SyncLock Then Throw
To True Try TypeOf Unicode
Until volatile When While With
WithEvents WriteOnly Xor eval extends
instanceof package var
文件名、文件目錄名
1. 全部單詞首字母大寫緊靠在一起。第一個單詞也必須大寫。只有一個單詞也必須大寫。不允許使用下劃線連接。明明中一般不允許出現數字。（特殊情形除外）
2. 擴展名必須全部小寫。
3. 應用程序缺省首頁一定是Default.aspx。
4. 允許使用修飾性的名詞詞組，動詞-名詞的支配結構詞組來表示aspx文件名。(例如MemberDetails.aspx) aspx文件名必須用詞準確。使用合適的單複數形式及動詞時態形式。
NameSpace命名
採用以下形式命名namespace:
CompanyName.TechnologyName[.Feature][.Design]
Pascal形式
應使用解決方案的名稱或者開發代號開頭.
如果作爲產品出售, 應以公司品牌開頭.
同一個解決方案，應儘量寫在同一個頂級NameSpace中。
每個項目應設置一個二級NameSpace. 並以項目名命名.
如果名詞有複數意義, 應採用其複數形式. 例如 Nestle.Web.UserControls.
不允許namespace和類重名.
類命名
1. 必須使用Pascal形式
2. 類名選詞必須可以完全準確地表示其含義。不允許使用晦澀、不常用的詞彙。也避免選擇意義太廣泛容易發生歧異的詞。例如表示車輛應選用Vehicles, 而不宜選用Cars. 員工應選用Employees, 而不宜選用Personels. 一般而言，詞彙的選用必須在項目開始以前經過充分討論，列出詞彙表。各成員應嚴格遵守選詞規則。避免同一個意義使用兩個不同的詞彙的情況。
3. 必須使用名詞或者名詞複合詞，如果僅具有動詞含義， 則使用其主語形態。例如Importor.
4. 謹慎的使用縮寫詞
5. 不允許使用表示數據類型的前綴.
6. 不允許使用下劃線連接
7. 使用複合詞來表示派生類. 例如派生自LinkButton的類可命名爲 SubmitLink. 又如 DataAccessException.
8. 接口一般以I爲前綴. 並且第二個字母也大寫.
9. 使用相同的詞彙表示接口和相關類例如:
public interface IComponent
{
}
public class Component: IComponent
{
}
Method命名
1. 使用動詞-名詞的方法來命名對給定對象執行特定操作的例程，如 CalculateInvoiceTotal(), RemoveAll(), GetCharArray(), Invoke()
2. 方法名必須可以詳盡描述其意義。
Property命名
1. 使用名詞或者名詞複合詞.
2. 有複數意義時應使用其複數形式.
3. 不要與其數據類型相同
4. 在面向對象的語言中，在類屬性的名稱中包含類名是多餘的，如 Book.BookTitle。而是應該使用 Book.Title。
5. 布爾值屬性應該包含 Is，這意味着 Yes/No 或 True/False 值，如 IsFileFound。
6. 使用#Region將所有Property定義組織在一起. 以便管理源代碼.
7. 註釋必須以 “公共特性: “開頭
8. 如果有缺省值則直接賦值給相關私有成員變量
Event命名
1. 使用EventHandler後綴來標識事件處理器.
2. 通常指定sender和e兩個參數. sender類型總是object. 而e與事件所對應的Exception類型相同.
3. 使用動詞表示事件. 例如Click, 或者名詞動詞組成的複合結構. 例如TaskAbort.
4. 使用進行時態表示事件發生之前, 使用過去時態表示事件發生之後, 例如TaskAborting和TaskAborted.
Web Control命名
1. 必須使用有意義的名字來表示所使用的web control。
2. 控件必須可以說明自身類型。 例如LinkButton類型的控件，其ID必須以Link結尾。以下是基本控件類型與後綴的對應關係：
a) LinkButton Link 舉例: SaveInformationLink
b) TextBox Box 舉例: UserNameBox
c) DropDownList List 舉例: LocaleList
d) Label Label 舉例: BirthDateLabel
e) Panel Panel 舉例: DetailFormPanel
f) Repeater Repeater 舉例: TaskRepeater
g) 其餘可依照規則類推
數據庫命名
1. 表名稱, 列名稱一律只允許小寫. 嚴禁使用大小寫混排的數據庫命名
2. 應使用常用英文詞彙的正確完整形式, 不允許任何形式的縮寫或簡寫.
3. 連接多個單詞時, 使用下劃線
4. 表名稱具有複數意義時, 使用名詞的正確的複數形式。
5. 一般情況下. 列名稱不應包含表名或者表名的任何形式。 列名不允許使用統一的前綴。
6. 關鍵數據對象表使用單個名詞。 爲區別開來, 非關鍵數據對象表一律使用複合名稱. 例如members(會員), member_messages(會員收件箱).
7. 字典表(僅用來表示索引之和名稱對應關係的表)一律以相同的前綴開始. 並且使用名詞的單數形式. 例如infr_locale(地域名索引表)
8. 字典表主鍵一律使用index_id名稱(小寫),並且是varchar類型.
9. 基層非關鍵表必須包含自動增加類型的Int主鍵, 而且名稱必須是pkid(primary key ID)。例如記錄用戶登錄日誌的表.
10. 視圖命名，應以_view詞根結尾。
11. 不允許給存儲過程加上sp_前綴。（sp_前綴是系統存儲過程。）存儲過程應以動詞-名詞的支配結構詞組。並且習慣性地以insert_, update_, select_, delete_開頭。
編碼規範
C#代碼
在開發中保持良好的編碼規範是十分重要的。編碼規範和約定必須能明顯改善代碼可讀性，並有助於代碼管理、分類。
1. 必須使用智能縮進代碼。並且製表符和縮進大小均爲4字符。 不允許插入空格縮進。（使用VISUAL STUDIO.NET的缺省設置）。
2. 在代碼中必須垂直對其左右花括號。不允許將左右花括號寫在一行上。
3. 同一行僅能容納一條語句.
4. 當一行內容太長而必須換行時，在後面換行代碼中要使用縮進格式，如下：
string inserString = "Insert Into TableName
(username,password,email,sex,address)"
5. 推薦每行語句以this開頭以便使用代碼助手. 加速書寫效率與準確性。
6. 儘量不給較長語句換行以提高可讀性。 (經驗證明將一不可分割的語句換行將帶來閱讀和維護上的困難。)
代碼組織結構
1. 採用如下順序組織類中的代碼:
類說明(註釋)
名稱那空間聲明
using語句組
類說明
類聲明
私有變量
公共屬性與相應私有變量組
方法聲明
2. 公共屬性和相應私有變量必須寫在一起. 並且一起被註釋註釋
例如:
/// <summary>
/// 公共特性(property): 資源文件(圖像文件及腳本資源)引用路徑
/// 相對於應用程序根路徑的地址, 可不以/符號結尾
/// </summary>
private string resourcePath
public string ResourcePath
{…
}
CODE BEHIDN組織結構
1. 採用如下順序組織類中的代碼:
類說明(註釋)
using語句組
名稱空間聲明
類說明
類聲明
ASPX所使用ASPX標準控件
ASPX所使用USER CONTROL
ASPX所使用CUSTOM CONTROL
私有變量
private void Page_Load(object sender, System.EventArgs e)方法實現
#region Web 窗體設計器生成的代: override protected void OnInit(EventArgs e)
自定義事件處理: 方法定義
2. 註釋某自定義事件處理方法必須註明事件觸發時的情景. 比如 ”檢查重名”! 事件處理, 其中雙引號和驚歎號內引用的詞彙爲前臺所見的控件表現.通常時一個按鈕或者一個鏈接的文本. 可另起一行進一步說明該過程.
空行與空格
1. 在類定義, 方法定義, 公共屬性定義前留一空行
1. 邏輯代碼段前留一空行
2. 逗號後留一空格
3. 運算符前後都有一空格. 但用於for循環大短語句除外.(僅在分號後留一空格)
4. 不允許出現多餘空行和空格.
5. 定義公共屬性的get和set過程之間不留空行
註釋
1. 註釋時連寫入三個斜線符號, Visual Studio IDE C#編輯器會自動產生/// <summry> 幫助產生標準XML註釋, 在註釋模塊, 類, 重要特性, 方法時必須使用, 而行間註釋不能使用
2. 註釋必須使用完整的中文陳述性語句. 避免註釋產生多義性而更難於理解.
3. 避免多餘的或不恰當的註釋. 或幽默的可有可無的註釋.
4. 註釋中必須使用書面語言. 避免使用口語或非正式的措辭. 註釋不可出現錯別字或多餘的語氣詞.
5. 註釋用用到的標點符號必須爲英文的普通標點符號.
6. 不允許用一整行星號或者斜線來標記註釋.
7. 模塊註釋: 書寫於.CS文件開頭. 分行註明模塊名, 意義及功能, 作者, 編寫時間. 修改人員須註明修改人姓名及時間. 以上項必須全部使用中文. 日期格式採用 2004-2-29 格式 註明24小時制時間, 精確到分鐘.
8. 類註釋: 書寫於類定義緊上方. 說明主要功能. 使用的算法以及注意事項. 可分行說明.
9. 行間註釋: 以雙斜線開始。必須先於被註釋的代碼. 並且要緊挨着代碼行.許在行尾增加註釋. 這一情況在分別註釋多行代碼時除外.
10. 註釋中如出現中英文混排，應注意使用適當的大小寫拼寫形式。如果英文做爲單字出現，則使用全部小寫。 （專有名詞，組織、公司名，以及縮寫除外。）如出現由多個單詞組成的專有名詞，則每個單詞首字母大寫。如Microsoft Internet Explorer.
T-SQL 編程
1. SQL 文本命令關鍵字必須全部使用大寫形式。
2. 涉及到的數據庫命名嚴格使用其原有形式。