需求:
(一)命名总体规则
(1)注释规范
a) 注释要求英文及英文的标点符号。
b) 注释中,应标明对象的完整的名称及其用途,但应避免对代码过于详细描述。
c) 每行注释的最大长度为100个字符。
d)将注释与注释分隔符用一个空格分开。
e) 不允许给注释加外框。
f)编码的同时书写注释。
g)重要变量必须有注释。
h)变量注释和变量在同一行,所有注释必须对齐,与变量分开至少两个“Tab”键。
如:int treeLevel, treeItemCount; // level ....tree level
// count ....count of tree items
string sql; // SQL
i)典型算法必须有注释。
j)在循环和逻辑分支地方的上行必须就近书写注释。
k)程序段或语句的注释在程序段或语句的上一行
l) 在代码交付之前,必须删掉临时的或无关的注释。
m)为便于阅读代码,每行代码的长度应少于100个字符。
(2)自建代码文件注释
由于存在 TFS 之类的管理系统,此部分不特别做要求
对于自己创建的代码文件(如函数、脚本),在文件开头,一般编写如下注释:
/******************************************************
FileName:
Writer:
create Date:
Rewriter:
Rewrite Date:
Main Content(Function Name、parameters、returns)
******************************************************/
(3)模块(类)注释
由于存在 TFS 之类的管理系统,此部分不特别做要求
模块开始必须以以下形式书写模块注释:
///<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>
(4)类属性注释
在类的属性必须以以下格式编写属性注释:
/// <summary>
/// <Properties depiction>
/// </summary>
(5)方法注释
在类的方法声明前必须以以下格式编写注释
/// <summary>
///<对该方法的说明>
/// </summary>
/// <param name="<参数名称>"><参数说明></param>
/// <returns>
///<对方法返回值的说明,该说明必须明确说明返回的值代表什么含义>
/// </returns>
/// <exception cref="ArgumentNullException">异常引发的条件。</exception>
(6)代码间注释
代码间注释分为单行注释和多行注释:
单行注释:
//<单行注释>
多行注释:
/*
多行注释1
多行注释2
多行注释3
*/
代码中遇到语句块时必须添加注释(if,for,foreach,……),添加的注释必须能够说明此语句块作用和实现手段(所用算法等等)。
(二)命名规范
参见名称规则
即使对于可能仅出现在几个代码行中的生存期很短的变量,仍然使用有意义的名称。仅对于短循环索引使用单字母变量名,如 i 或 j。
在变量名中使用互补对,如 min/max、begin/end 和 open/close。
(三) 补充说明
关于匈牙利命名法
对于 Visual Studio 这类强大开放工具而言,匈牙利命名法是一种累赘。因此,我们不应当在 C# 或者 VB.Net 中使用它。但是,对于 JavaScript 而言,由于 IDE 的不方便,有时我们应当适当使用匈牙利命名法来帮助理解变量的含义。不过这时,下划线是没有必要的,它只会增加你的输入时间;而参数、成员变量的前缀也是没有必要的。
关于 JavaScript
希望大家尽量使用面向对象的思想编写 JavaScript。JavaScript 的代码编写规则应当和 C# 之类的一致(全局变量命名除外)。
关于控件的命名
对于 HTML 控件、服务器控件或者 Windows Form 控件的命名应当采用不带下划线的匈牙利命名法。这样可以有效避免命名冲突。(见附表2)
(四)编码规则
(0) 参数和返回值的验证
验证一切输入的参数,除非某个参数允许取所有的值。对应参数非法的,应当抛出异常通知调用者参数错误,并且应当指出是那个参数出错、合理的值应当是怎样的。
比如,要看传入的非空的引用类型,但调用者传入一个空引用的,应当引发 ArgumentNullException;对于要求传入正数的参数,但调用者传入一个负数的,应当引发 ArgumentOutOfRangeException 并告知正确的范围。
如果允许默认参数的,考虑使用重载,或者修复非法的参数。
接收函数的返回值后,应当先验证返回值是否为合法的或者是预期的,然后在使用;如果返回值不正确,应当进行相应的处理。
(1)错误检查规则
a) 编程中要考虑函数的各种执行情况,尽可能处理所有流程情况。
b)检查所有的系统调用的错误信息,除非要忽略错误。
c)将函数分两类:一类为与屏幕的显示无关, 另一类与屏幕的显示有关。对于与屏幕显示无关的函数,函数通过返回值来报告错误。对于与屏幕显示有关的函数,函数要负责向用户发出警告,并进行错误处理。
d)错误处理代码一般放在函数末尾。
e)对于通用的错误处理,可建立通用的错误处理函数,处理常见的通用的错误。
(2)大括号规则
将大括号放置在关键词下方的同列处,例如:
if ($condition)
{
...
}
while ($condition)
{
...
}
(3)缩进规则
使用一个4个空格为每层次缩进。例如:
function func()
{
if (something bad)
{
if (another thing bad)
{
while (more input)
{
}
}
}
}
(4)小括号规则
a) 不要把小括号和关键词(if 、while等)紧贴在一起,要用空格隔开它们。
b) 不要把小括号和函数名紧贴在一起。
c) 除非必要,不要在Return返回语句中使用小括号。因为关键字不是函数,如果小括号紧贴着函数名和关键字,二者很容易被看成是一体的。
(5)If Then Else规则
如果你有用到else if 语句的话,通常最好有一个else块以用于处理未处理到的其他情况。可以的话放一个记录信息注释在else处,即使在else没有任何的动作。其格式为:
if (条件1) // 注释
{
}
else if (条件2) // 注释
{
}
else // 注释
{
}
注:if 和循环的嵌套最多允许4层
(6)比较规则
总是将恒量放在等号/不等号的左边。一个原因是假如你在等式中漏了一个等号,语法检查器会为你报错。第二个原因是你能立刻找到数值而不是在你的表达式的末端找到它。
例如
if ( 6 == $errorNum ) ...
(7) Case规则
default case总应该存在,如果不允许到达,则应该保证:若到达了就会触发一个错误。Case的选择条件最好使用int或string类型。
(8)单语句规则
除非这些语句有很密切的联系,否则每行只写一个语句。
(9)单一功能规则
原则上,一个程序单元(函数、例程、方法)只完成一项功能。
(10)简单功能规则
原则上,一个程序单元的代码应该限制在一页内(25~30行)。
(11)明确条件规则
不要采用缺省值测试非零值。例如:使用“if ( 0 != f( ) )”而不用“if ( f( ) )”。
(12)选用FALSE规则
大部分函数在错误时返回FALSE、0或NO之类的值,但在正确时返回值就不定了(不能用一个固定的TRUE、1或YES来代表),因此检测一个布尔值时应该用FALSE、0、NO之类的不等式来代替。例如:使用“if ( FALSE != f( ) )”而不用“if (TRUE == f( ) )”。
(13)独立赋值规则
嵌入式赋值不利于理解程序,同时可能回造成意想不到的副作用,应尽量编写独立的赋值语句。例如:使用“a = b + c ; e = a + d;”而不用“e = ( a = b + c ) + d ”。
(14)定义常量规则
对于代码中引用的常量(尤其是数字),应该定义成常量类型,在代码中引用名字而不直接引用值。
(15)模块化规则
某一功能,如果重复实现一遍以上,即应考虑模块化,将它写成通用函数。并向小组成员发布。同时要尽可能利用其它人的现成模块。
。
(五)编程准则
(1)变量使用
a) 不允许随意定义全局变量。
b) 一个变量只能有一个用途;变量的用途必须和变量的名称保持一致。
c) 所有变量都必须在类和函数最前面定义,并分类排列。
(2)数据库操作
a) 查找数据库表或视图时,只能取出确实需要的那些字段。
b) 使用无关联子查询,而不要使用关联子查询。
c) 清楚明白地使用列名,而不能使用列的序号。
d) 用事务保证数据的完整性。
e) 使用对数据库链接、数据库命令等使用using 语句,避免忘记释放资源。
(3)对象使用
a) 尽可能晚地创建对象,并且尽可能早地释放它。
b) 对于使用珍贵资源的对象(如数据库链接、文件流等),应该实现 IDisposable 接口并且尽量使用 using 语句。因为使用它的话,编译器会自动帮你生成正确的释放资源的代码。
正确实现 IDisposable 接口的方法:
class LargeResourceHolder : IDisposable
{
private bool disposed;
private DbConnection conn;
protected virtual void Dispose(bool disposing)
{
if(disposing) // 如果 disposing 为 true;则清理资源
{
if(conn != null)
{
conn.Close();
disposed = true;
}
}
// 如果继承自其它实现了 IDisposable 接口的类型,还用过调用
// base.Dispose(disposing);
}
public void Dispose()
{
Dispose(true);
GC.SupressFinilizer(this);
}
}
(4)模块设计原则
a) 不允许随意定义公用的函数和类。
b) 函数功能单一,不允许一个函数实现两个及两个以上的功能。
c) 不能在函数内部使用全局变量,如要使用全局变量,应转化为局部变量。
d) 函数与函数之间只允许存在包含关系,而不允许存在交叉关系。即两者之间只存在单方向的调用与被调用,不存在双向的调用与被调用。
e) 小心使用递归,务必检查是否设置了终止条件。如果合适,改成非递归的形式。
(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) 不要轻易用条件分支去替换逻辑表达式
(6)函数返回值原则
1) 函数返回值
避免使用结构体等复杂类型
使用bool类型:该函数只需要获得成功或者失败的返回信息时候
使用int 类型或者错误代码枚举:错误代码用负数表示,成功返回0
这条规则不适用创建对象、或者查询对象等操作。
2) 返回多个同类型数据
考虑返回一个集合而不是一个数组或者链表。对应抽象程度要求高的,应当返回 ICollection 泛型接口。
(六)输入控制校验规则
(1)登陆控制
用户登陆ID和登陆密码,要限定输入长度范围,必须检查输入合法性。
(2) 数据录入控制
a) TextBox输入
1、 要保持用户输入和数据库接收的长度一致
2、 必须进行输入合法性校验
如:E_mail格式 XXX@XXX.XXX...
电话格式 020-12345678
(020)12345678
邮政编码是六位
b) 除CheckBox、RadioButton外,禁止在DataGrid内嵌入其他编辑控件,用以添加编辑数据
3、 使用正则表达式进行字符串解析,而不是定界符
4、 使用 Xml 进行传输,而不是纯文本。
附件1:数据类型缩写表(不推荐使用)
数据类型 | 缩写 |
string | str |
int | i |
char | sz |
sbyte | sb |
byte | bt |
uint | ui |
long | l |
ulong | ul |
float | f |
double | d |
bool | b |
decimal | dec |
附件2:服务器控件名缩写表(推荐使用)
a、web控件
web控件名 | 缩写 |
AdRotator | art |
Button | cmd |
Calendar | cd |
CheckBox | chk |
CheckBoxList | chkl |
CompareValidator | cpv |
CustomValidator | ctv |
DataGrid | dg |
DataList | dl |
DropDownList | ddl |
HyperLink | hl |
Image | img |
ImageButton | Icmd |
Label | lab |
LinkButton | lcmd |
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 | hcmd |
HtmlForm | hform |
HtmlGenericControl | hgc |
HtmlImage | himg |
HtmlInputButton(按钮) | htxt |
HtmlInputButton(重置) | hrcmd |
HtmlInputButton(提交) | hccmd |
HtmlInputCheckBox | hick |
HtmlInputFile | hifile |
HtmlInputHidden | hihidden |
HtmlInputImage | hiimg |
HtmlInputRadioButton | hirb |
HtmlInputText(密码) | hpwd |
HtmlInputText(文本) | hitxt |
HtmlSelect | hslt |
HtmlTable | htab |
HtmlTableCell | htc |
HtmlTableRow | htr |
HtmlTextArea | htxta |