咨詢電話：023-6276-4481
咨詢電話：023-6276-4481
熱門文章
電 話：023-6276-4481
郵箱：broiling@qq.com
地址：重慶市南岸區(qū)亞太商谷6幢25-2
代碼編寫規(guī)范說明書（c#.net與asp.net）
1 目的
2 范圍
3 注釋規(guī)范
3.1 概述
3.2 自建代碼文件注釋
3.3 模塊（類）注釋
3.4 類屬性注釋
3.5 方法注釋
3.6 代碼間注釋
4 命名總體規(guī)則
5 命名規(guī)范
5.1 變量（Variable）命名
5.2 常量命名
5.3 類（Class）命名
5.4 接口（Interface）命名
5.5 方法（Method）命名
5.6 名稱空間Namespace）命名
6 編碼規(guī)則
6.1 錯(cuò)誤檢查規(guī)則
6.2 大括號規(guī)則
6.3 縮進(jìn)規(guī)則
6.4 小括號規(guī)則
6.5 If Then Else規(guī)則
6.6 比較規(guī)則
6.7 Case規(guī)則
6.8 對齊規(guī)則
6.9 單語句規(guī)則
6.10 單一功能規(guī)則
6.11 簡單功能規(guī)則
6.12 明確條件規(guī)則
6.13 選用FALSE規(guī)則
6.14 獨(dú)立賦值規(guī)則
6.15 定義常量規(guī)則
6.16 模塊化規(guī)則
6.17 交流規(guī)則
7 編程準(zhǔn)則
7.1 變量使用
7.2 數(shù)據(jù)庫操作
7.3 對象使用
7.4 模塊設(shè)計(jì)原則
7.5 結(jié)構(gòu)化要求
7.6 函數(shù)返回值原則
8 代碼包規(guī)范
8.1 代碼包的版本號
8.2 代碼包的標(biāo)識
9 代碼的控制
9.1 代碼庫/目錄的建立
9.2 代碼歸檔
10 輸入控制校驗(yàn)規(guī)則
10.1 登陸控制
10.2 數(shù)據(jù)錄入控制
附件1：數(shù)據(jù)類型縮寫表
附件2：服務(wù)器控件名縮寫表
1 目的
一.為了統(tǒng)一公司軟件開發(fā)設(shè)計(jì)過程的編程規(guī)范
二.使網(wǎng)站開發(fā)人員能很方便的理解每個(gè)目錄,變量，控件，類，方法的意義
三.為了保證編寫出的程序都符合相同的規(guī)范，保證一致性、統(tǒng)一性而建立的程序編碼規(guī)范。
四.編碼規(guī)范和約定必須能明顯改善代碼可讀性，并有助于代碼管理、分類范圍適用于企業(yè)所有基于.NET平臺的軟件開發(fā)工作
2 范圍
本規(guī)范適用于開發(fā)組全體人員，作用于軟件項(xiàng)目開發(fā)的代碼編寫階段和后期維護(hù)階段。
3 注釋規(guī)范
3.1 概述
a) 注釋要求英文及英文的標(biāo)點(diǎn)符號。
b) 注釋中，應(yīng)標(biāo)明對象的完整的名稱及其用途，但應(yīng)避免對代碼過于詳細(xì)的描述。
c) 每行注釋的最大長度為100個(gè)字符。
d) 將注釋與注釋分隔符用一個(gè)空格分開。
e) 不允許給注釋加外框。
f) 編碼的同時(shí)書寫注釋。
g) 重要變量必須有注釋。
h) 變量注釋和變量在同一行，所有注釋必須對齊，與變量分開至少四個(gè)“空格”鍵。
如：int m_iLevel,m_iCount; // m_iLevel ....tree level
// m_iCount ....count of tree items
string m_strSql; //SQL
i) 典型算法必須有注釋。
j) 在循環(huán)和邏輯分支地方的上行必須就近書寫注釋。
k) 程序段或語句的注釋在程序段或語句的上一行
l) 在代碼交付之前，必須刪掉臨時(shí)的或無關(guān)的注釋。
m) 為便于閱讀代碼，每行代碼的長度應(yīng)少于100個(gè)字符。
3.2 自建代碼文件注釋
對于自己創(chuàng)建的代碼文件（如函數(shù)、腳本），在文件開頭，一般編寫如下注釋：
/******************************************************
FileName:
Copyright (c) 2004-xxxx *********公司技術(shù)開發(fā)部
Writer:
create Date:
Rewriter:
Rewrite Date:
Impact:
Main Content（Function Name、parameters、returns）
******************************************************/
3.3 模塊（類）注釋
模塊開始必須以以下形式書寫模塊注釋：
///<summary>
///Module ID：<模塊編號，可以引用系統(tǒng)設(shè)計(jì)中的模塊編號>
///Depiction：<對此類的描述，可以引用系統(tǒng)設(shè)計(jì)中的描述>
///Author：作者中文名
///Create Date：<模塊創(chuàng)建日期，格式：YYYY-MM-DD>
///</summary>
如果模塊只進(jìn)行部分少量代碼的修改時(shí)，則每次修改須添加以下注釋：
///Rewriter Rewrite Date：<修改日期:格式Y(jié)YYY-MM-DD> Start1：
/* 原代碼內(nèi)容*/
///End1：
將原代碼內(nèi)容注釋掉，然后添加新代碼使用以下注釋：
///Added by Add date：<添加日期，格式：YYYY-MM-DD> Start2：
///End2：
如果模塊輸入輸出參數(shù)或功能結(jié)構(gòu)有較大修改，則每次修改必須添加以下注釋：
///<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="<參數(shù)名稱>"><參數(shù)說明></param>
/// <returns>
///<對方法返回值的說明，該說明必須明確說明返回的值代表什么含義>
/// </returns>
///Writer：作者中文名
///Create Date：<方法創(chuàng)建日期，格式：YYYY-MM-DD>
3.6 代碼間注釋
代碼間注釋分為單行注釋和多行注釋：
//<單行注釋>
/*多行注釋1
多行注釋2
多行注釋3*/
代碼中遇到語句塊時(shí)必須添加注釋（if,for,foreach,……）,添加的注釋必須能夠說明此語句塊的作用和實(shí)現(xiàn)手段（所用算法等等）。
4 命名總體規(guī)則
? 名字應(yīng)該能夠標(biāo)識事物的特性。
? 名字一律使用英文單詞，而不能為拼音。
? 名字盡量不使用縮寫，除非它是眾所周知的。
? 名字可以有兩個(gè)或三個(gè)單詞組成，但不應(yīng)多于三個(gè)，控制在3至30個(gè)字母以內(nèi)。
? 在名字中，多個(gè)單詞用大寫第一個(gè)字母（其它字母小寫）來分隔。例如：IsSuperUser。
? 名字盡量使用前綴而不是后綴。
? 名字中的單詞盡量使用名詞，如有動詞，也盡量放在后面。例如：FunctionUserDelete（而不是FunctionDeleteUser）。
5 命名規(guī)范
5.1 變量（Variable）命名
a) 程序文件(*.cs)中的變量命名
程序中變量名稱 = 變量的前綴 +代表變量含意的英文單詞或單詞縮寫。
? 類模塊級的變量請用“m_” +數(shù)據(jù)類型縮寫作為前綴（其中，m 為“memory”縮寫，數(shù)據(jù)類型縮寫見附件中的《數(shù)據(jù)類型縮寫表》）。
public class hello
{
private string m_strName;
private DateTime m_dtDate;
}
? 類的屬性所對應(yīng)的變量，采用屬性名前加“m_”+ 類型縮寫前綴的形式
public class hello
{
private string m_strName;
public string Name
{
get
{
return m_strName;
}
}
}
過程級的變量使用類型縮寫前綴
public class hello
{
void say()
{
string strSayWord;
}
}
? 過程的參數(shù)使用“p_”+ 類型縮寫作為前綴（其中，p 為“parameter”縮寫）
public class hello
{
void say(string p_strSayWord)
{
}
}
補(bǔ)充說明：
針對異常捕獲過程中的Exception變量命名，在沒有沖突的情況下，統(tǒng)一命名為exp；
如果有沖突的情況下，可以用“exp”+ 標(biāo)志名稱，如：expSql。
Try
{
//your code
try
{
//code
}
catch(Exception exp)
{
//your code
}
}
catch(Exception expSql)
{
//your code
}
補(bǔ)充：如果捕獲異常不需要作任何處理，則不需要定義Exception實(shí)例。
例：
try
{
//your code
}
catch( Exception exp)
{
}
? 鑒于大多數(shù)名稱都是通過連接若干單詞構(gòu)造的，請使用大小寫混合的格式以簡化它們的閱讀。每個(gè)單詞的第一個(gè)字母都是大寫.
? 即使對于可能僅出現(xiàn)在幾個(gè)代碼行中的生存期很短的變量，仍然使用有意義的名稱。僅對于短循環(huán)索引使用單字母變量名，如 i 或 j。
? 在變量名中使用互補(bǔ)對，如 min/max、begin/end 和 open/close。
? 不要使用原義數(shù)字或原義字符串，如 For (i = 1;i <= 7;i++)。而是使用命名常數(shù)，如 For (i = 1;i <= NUM_DAYS_IN_WEEK;i++) 以便于維護(hù)和理解。
b) 控件命名
控件命名 = 控件名稱前二到三個(gè)字母 + 名稱，如Labl控件（lblUserName）
5.2 常量命名
常量名也應(yīng)當(dāng)有一定的意義，格式為 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 個(gè)字符，但是，超過 25 到 30 個(gè)字符的名稱比較笨拙。此外，要想取一個(gè)有實(shí)際意義的名稱，清楚地表達(dá)變量或常量的用途，25 或 30 個(gè)字符應(yīng)當(dāng)足夠了。
5.3 類（Class）命名
a) 名字應(yīng)該能夠標(biāo)識事物的特性。
b) 名字盡量不使用縮寫，除非它是眾所周知的。
c) 名字可以有兩個(gè)或三個(gè)單詞組成，但通常不應(yīng)多于三個(gè)。
d) 在名字中，所有單詞第一個(gè)字母大寫。例如 IsSuperUser，包含ID的，ID全部大寫，如CustomerID。
e) 使用名詞或名詞短語命名類。
f) 少用縮寫。
g) 不要使用下劃線字符 (_)。
例： public class FileStream
public class Button
public class String
5.4 接口（Interface）命名
和類命名規(guī)范相同，唯一區(qū)別是 接口在名字前加上“I”前綴
例：
interface IDBCommand;
interface IButton;
5.5 方法（Method）命名
和類命名規(guī)范相同。
5.6 命名空間（NameSpace）命名
和類命名規(guī)范相同。
6 編碼規(guī)則
6.1 錯(cuò)誤檢查規(guī)則
a) 編程中要考慮函數(shù)的各種執(zhí)行情況，盡可能處理所有流程情況。
b) 檢查所有的系統(tǒng)調(diào)用的錯(cuò)誤信息，除非要忽略錯(cuò)誤。
c) 將函數(shù)分兩類：一類為與屏幕的顯示無關(guān)，另一類與屏幕的顯示有關(guān)。對于與屏幕顯示無關(guān)的函數(shù)，函數(shù)通過返回值來報(bào)告錯(cuò)誤。對于與屏幕顯示有關(guān)的函數(shù)，函數(shù)要負(fù)責(zé)向用戶發(fā)出警告，并進(jìn)行錯(cuò)誤處理。
d) 錯(cuò)誤處理代碼一般放在函數(shù)末尾。
e) 對于通用的錯(cuò)誤處理，可建立通用的錯(cuò)誤處理函數(shù)，處理常見的通用的錯(cuò)誤。
6.2 大括號規(guī)則
將大括號放置在關(guān)鍵詞下方的同列處，例如：
if ($condition) while ($condition)
{ {
... ...
} }
6.3 縮進(jìn)規(guī)則
使用一個(gè)“Tab”為每層次縮進(jìn)。例如：
function func()
{
if (something bad)
{
if (another thing bad)
{
while (more input)
{
}
}
}
}
6.4 小括號規(guī)則
a) 不要把小括號和關(guān)鍵詞（if 、while等）緊貼在一起，要用空格隔開它們。
b) 不要把小括號和函數(shù)名緊貼在一起。
c) 除非必要，不要在Return返回語句中使用小括號。因?yàn)殛P(guān)鍵字不是函數(shù)，如果小括號緊貼著函數(shù)名和關(guān)鍵字，二者很容易被看成是一體的。
6.5 If Then Else規(guī)則
如果你有用到else if 語句的話，通常最好有一個(gè)else塊以用于處理未處理到的其他情況?？梢缘脑挿乓粋€(gè)記錄信息注釋在else處，即使在else沒有任何的動作。其格式為：
if (條件1) // 注釋
{
}
else if (條件2) // 注釋
{
}
else // 注釋
{
}
注：if 和循環(huán)的嵌套最多允許4層
6.6 比較規(guī)則
總是將恒量放在等號/不等號的左邊。一個(gè)原因是假如你在等式中漏了一個(gè)等號，語法檢查器會為你報(bào)錯(cuò)。第二個(gè)原因是你能立刻找到數(shù)值而不是在你的表達(dá)式的末端找到它。例如：
if ( 6 == $errorNum ) ...
6.7 Case規(guī)則
default case總應(yīng)該存在，如果不允許到達(dá)，則應(yīng)該保證：若到達(dá)了就會觸發(fā)一個(gè)錯(cuò)誤。Case的選擇條件最好使用int或string類型。
6.8 對齊規(guī)則
變量的申明和初始化都應(yīng)對齊。例如：
int m_iCount;
int i,j;
float m_fIncome,m_fPay;
m_iCount = 0;
i = 1;
m_fIncome = 0.3;
6.9 單語句規(guī)則
除非這些語句有很密切的聯(lián)系，否則每行只寫一個(gè)語句。
6.10 單一功能規(guī)則
原則上，一個(gè)程序單元（函數(shù)、例程、方法）只完成一項(xiàng)功能。
6.11 簡單功能規(guī)則
原則上，一個(gè)程序單元的代碼應(yīng)該限制在一頁內(nèi)（25~30行）。
6.12 明確條件規(guī)則
不要采用缺省值測試非零值。例如：使用“if ( 0 != f( ) )”而不用“if ( f( ) )”。
6.13 選用FALSE規(guī)則
大部分函數(shù)在錯(cuò)誤時(shí)返回FALSE、0或NO之類的值，但在正確時(shí)返回值就不定了（不能用一個(gè)固定的TRUE、1或YES來代表），因此檢測一個(gè)布爾值時(shí)應(yīng)該用 FALSE、0、NO之類的不等式來代替。例如：使用“if ( FALSE != f( ) )” 而不用“if (TRUE == f( ) )”。
6.14 獨(dú)立賦值規(guī)則
嵌入式賦值不利于理解程序，同時(shí)可能回造成意想不到的副作用，應(yīng)盡量編寫?yīng)毩⒌馁x值語句。例如：使用“a = b + c ; e = a + d;”而不用“e = ( a = b + c ) + d ”。
6.15 定義常量規(guī)則
對于代碼中引用的常量（尤其是數(shù)字），應(yīng)該define成一個(gè)大寫的名字，在代碼中引用名字而不直接引用值。
6.16 模塊化規(guī)則
某一功能，如果重復(fù)實(shí)現(xiàn)一遍以上，即應(yīng)考慮模塊化，將它寫成通用函數(shù)。并向小組成員發(fā)布。同時(shí)要盡可能利用其它人的現(xiàn)成模塊。
6.17 交流規(guī)則
共享別人的工作成果，向別人提供自己的工作成果。
在具體任務(wù)開發(fā)中，如果有其它的編碼規(guī)則，則在相應(yīng)的軟件開發(fā)計(jì)劃中予以明確定義。
7 編程準(zhǔn)則
7.1 變量使用
a) 不允許隨意定義全局變量。
b) 一個(gè)變量只能有一個(gè)用途；變量的用途必須和變量的名稱保持一致。
c) 所有變量都必須在類和函數(shù)最前面定義，并分類排列。
7.2 數(shù)據(jù)庫操作
a) 查找數(shù)據(jù)庫表或視圖時(shí)，只能取出確實(shí)需要的那些字段。
b) 使用無關(guān)聯(lián)子查詢，而不要使用關(guān)聯(lián)子查詢。
c) 清楚明白地使用列名，而不能使用列的序號。
d) 用事務(wù)保證數(shù)據(jù)的完整性。
7.3 對象使用
a) 盡可能晚地創(chuàng)建對象，并且盡可能早地釋放它。
7.4 模塊設(shè)計(jì)原則
a) 不允許隨意定義公用的函數(shù)和類。
b) 函數(shù)功能單一，不允許一個(gè)函數(shù)實(shí)現(xiàn)兩個(gè)及兩個(gè)以上的功能。
c) 不能在函數(shù)內(nèi)部使用全局變量，如要使用全局變量，應(yīng)轉(zhuǎn)化為局部變量。
d) 函數(shù)與函數(shù)之間只允許存在包含關(guān)系，而不允許存在交叉關(guān)系。即兩者之間只存在單方向的調(diào)用與被調(diào)用，不存在雙向的調(diào)用與被調(diào)用。
7.5 結(jié)構(gòu)化要求
a) 禁止出現(xiàn)兩條等價(jià)的支路。
例如：if (a == 2)
else if (a== 3)
//
else if (a == 2)
//
else
//
b) 避免使用GOTO語句
c) 用 IF 語句來強(qiáng)調(diào)只執(zhí)行兩組語句中的一組。禁止 ELSE GOTO 和 ELSE RETURN。
d) 用 CASE 實(shí)現(xiàn)多路分支
e) 避免從循環(huán)引出多個(gè)出口。
f) 函數(shù)只有一個(gè)出口。
g) 不使用條件賦值語句。
h) 避免不必要的分支。
i) 不要輕易用條件分支去替換邏輯表達(dá)式
7.6 函數(shù)返回值原則
1） 函數(shù)返回值
避免使用結(jié)構(gòu)體等復(fù)雜類型
使用bool類型：該函數(shù)只需要獲得成功或者失敗的返回信息時(shí)候
使用int 類型：錯(cuò)誤代碼用負(fù)數(shù)表示，成功返回0
8 代碼包規(guī)范
本項(xiàng)目中，每個(gè)任務(wù)在完成一個(gè)穩(wěn)定的版本后，都應(yīng)打包并且歸檔。
8.1 代碼包的版本號
項(xiàng)目中，代碼包的版本號由圓點(diǎn)隔開的兩個(gè)數(shù)字組成，第一個(gè)數(shù)字表示發(fā)行號，第二個(gè)數(shù)字表示該版的修改號。具體用法如下：
1) 當(dāng)代碼包初版時(shí)，版本號為 V1.00；
2) 當(dāng)代碼包被局部修改或bug修正時(shí)，發(fā)行號不變，修改號第二個(gè)數(shù)字增1。例如，對初版代碼包作了第一次修訂，則版本號為 V1.01；
3) 當(dāng)代碼包在原有的基礎(chǔ)上增加部分功能，發(fā)行號不變，修改號第一個(gè)數(shù)字增1，例如，對V1.12版的基礎(chǔ)上增加部分功能，則新版本號為 V1.20；
4) 當(dāng)代碼包有重要修改或局部修訂累積較多導(dǎo)致代碼包發(fā)生全局變化時(shí)，發(fā)行號增1。例如，在 V1.15 版的基礎(chǔ)上作了一次全面修改，則新版本號為 V2.00。
8.2 代碼包的標(biāo)識
本項(xiàng)目所產(chǎn)生的代碼包都有唯一、特定的編碼，其構(gòu)成如下：
S-項(xiàng)目標(biāo)識-代碼包類型-版本號/序號
其中：
1) S：本項(xiàng)目的標(biāo)識，表明本項(xiàng)目是“XXXX”。
2) 項(xiàng)目標(biāo)識：簡要標(biāo)識本項(xiàng)目，此標(biāo)識適用于整個(gè)項(xiàng)目的文檔。
3) 代碼包類型：取自以下表的兩位字母編碼。
4) 版本號：本代碼包的版本號。
5) 序號：四位數(shù)字編碼，指明該代碼包在項(xiàng)目代碼庫的總序號。
例如：
一個(gè)Windows下RAR源碼的壓縮代碼包命名為： S-XXXX-WS-V1.02/0001
項(xiàng)目的代碼包分類表
類 型 編 碼 注 釋
RAR包
（web） 源碼文件 WS 源代碼文件包
編譯文件 WB 編譯文件包
安裝文件 WI 安裝文件包
源碼代碼 + 安裝文件 WA 源代碼和安裝文件包
項(xiàng)目中所有代碼包的標(biāo)識清單將在《項(xiàng)目開發(fā)計(jì)劃》中予以具體定義。
9 代碼的控制
9.1 代碼庫/目錄的建立
項(xiàng)目負(fù)責(zé)人在VSS中建立項(xiàng)目的文檔庫目錄，即為“Software”目錄，以便快速查詢。
9.2 代碼歸檔
所有代碼在完成一個(gè)穩(wěn)定的版本后，項(xiàng)目負(fù)責(zé)人都應(yīng)打包后，存放于VSS中該目的“Software”目錄下，并且依據(jù)代碼包的命名規(guī)范為代碼包分配一個(gè)唯一名稱。
10 輸入控制校驗(yàn)規(guī)則
10.1 登陸控制
用戶登陸ID和登陸密碼，要限定輸入長度范圍，必須檢查輸入合法性。
10.2 數(shù)據(jù)錄入控制
a) TextBox輸入
1、 要保持用戶輸入和數(shù)據(jù)庫接收的長度一致
2、 必須進(jìn)行輸入合法性校驗(yàn)
如：E_mail格式 XXX@XXX.XXX...
