C#代码开发规范
C#代码开发规范
文件状态: [√] 草稿 [ ] 正式 [ ] 修改 |
文件标识: |
|
当前版本: |
1.1 |
|
作 者: |
Empty |
|
联系电话: |
|
|
最后更新: |
2014-04-07 |
版本记录
日期 |
版本号 |
作者 |
说明 |
2014-4-2 |
1.0 |
Empty |
创建 |
2014-4-7 |
1.1 |
Empty |
添加前言、注释规范与编码规范 |
|
|
|
|
|
|
|
|
|
|
|
|
目 录
1. 前言... 4
1.1 编写目的... 4
1.2 适用范围... 4
1.3 基本要求... 4
2. 命名规范... 4
2.1 字母大小写约定... 4
2.1.1 说明... 4
2.1.2 Pascal风格... 4
2.1.3 Camel风格... 5
2.2 标识符的大小写规则... 5
2.3 通用命名约定... 5
2.3.1 选择名称... 5
2.3.2 字母缩写词... 6
2.4 命名空间命名... 6
2.5 类、结构和接口命名... 6
2.6 逻辑层类命名... 6
2.7 文件夹命名... 7
3. 注释规范... 7
3.1 模块(类)注释规范... 7
3.2 类属性注释规范... 7
3.3 方法注释规范... 7
3.4 代码间注释规范... 8
4. 编码规范... 9
1. 前言
1.1 编写目的
为了保证编写出的程序都符合相同的规范,保证一致性、统一性而建立的程序编码规范。
编码规范对于程序员而言尤为重要,有以下几个原因:
1) 一个软件的生命周期中,80%的花费在于维护。
2) 几乎没有任何一个软件,在其整个生命周期中,均由最初的开发人员来维护。
3) 编码规范可以改善软件的可读性,可以让程序员尽快而彻底地理解新的代码 。
每个软件开发人员都必须遵守统一的编码规范。
1.2 适用范围
本规范适用于《从零开始编写自己的C# 框架》的开发。
1.3 基本要求
尽量使代码简单直白。
2. 命名规范
2.1 字母大小写约定
2.1.1 说明
表达清晰的命名规范是程序规划的核心,如果规范的命名能清晰的表达出相应的功能,就可以让人“望文知意”,提高开发效率和系统的可维护性。反之,如果命名不能表达其含义,例如“aaa”、“bbb ()”,那么将适得其反。
2.1.2 Pascal风格
包含一到多个单词,每一个单词第一个字母大写,其余字母均小写。例如:HelloWorld、SetName等。
2.1.3 Camel风格
包含一到多个单词,第一个单词首字母小写,其余单词首字母大写。例如:name、productId等。
2.2 标识符的大小写规则
1) 除了参数与变量外,所有命名空间名称、类、函数、接口、属性等名称的命名,使用 Pascal 风格。
2) 参数与变量的命名,使用Camel风格。
2.3 通用命名约定
约定的是如何选择最适当的名称,这些准则适用于所有标识符命名。
2.3.1 选择名称
1) 请选择易读的英文名称
例如,英文 Order的意思为规则、次序、订购等,如果用在排序列中就不是很合适,用来表示订单则更具可读性。
可读性比详细描述更重要,比如表示坐标名称ScreenX就比ScreenHorizontally 更具可读性。
2) 除下划线外,不要使用连字符或任何其他非字母数字字符
在数据库表字段名称设计时,与其他表字段有关联时,适当的使用表名+下横线+字段名,可以更清晰的表现出该字段与关联表对应字段的关系。
比如产品分类表ProductClass有字段Id与Name,那么产品表绑定这两个字段的名称可命名为ProductClass_Id与ProductClass_Name,这样在查看产品表时就可以清晰的知道这两个字段与分类表的关系。
3) 避免使用与常用编程语言的关键字冲突的标识符
4) 变量和方法参数使用Camel 风格
例如:
string productName = "";
int number=0;
string sqlString="";
double averageScore=0.0;
Users users=new Users();
Users model=new Users();
Users userModel=new Users();
const string const_String = "";(不同公司有不同的约定,具体根据自己公司情况设置而定)
Private string GetProductName(int id)
{
return "";
}
5) 不要使用成员属性作为成员变量的前缀(其他变量命名也一样)
例如: 不要像Users m_users;这样定义成员变量,可以使用第4点的设置。
2.3.2 字母缩写词
1) 通常,不应使用缩写
2) 除非这种缩写已广泛接受,又或者团队当中大家都认可一种缩写
例如,使用 OnButtonClick,如果团队中普遍认可OnBtnClick这种写法也是可以的。
2.4 命名空间命名
命名空间命名采用Pascal风格,取名的一般规则如下。
CompanyName. ProjectName (公司名称.项目名称)
例如:
Microsoft.Office
需要用复数时,请使用复数。
例如,使用System.Collections而不是System.Collection。
需要缩写时,不需要加复数。
例如:使用System.IO而不是System.IOs。
2.5 类、结构和接口命名
1) 按照 Pascal 大小写格式,使用名词或名词短语为类、接口和值类型命名
2) 接口命名以字母 I 为前缀
例如:IComponent
3) 派生类的末尾使用基类名称
例如,从 Stream 继承的 Framework 类型以 Stream 结尾,从 Exception 继承的类型以 Exception 结尾。
2.6 逻辑层类命名
按照 Pascal 大小写格式,使用名词或名词短语命名,并加上后缀Logic
2.7 文件夹命名
文件夹以功能模块名称,按照 Pascal 大小写格式命名。
比如后端管理功能以及权限相关功能,全部放到Systems文件夹里。
3. 注释规范
3.1 模块(类)注释规范
模块开始必须以以下形式书写模块注释:
///<summary>
///模块编号:<模块编号,可以引用系统设计中的模块编号>
///作用:<对此类的描述,可以引用系统设计中的描述>
///作者:作者中文名
///编写日期:<模块创建日期,格式:YYYY-MM-DD>
///</summary>
如果模块有修改,则每次修改必须添加以下注释:
///<summary>
///Log编号:<Log编号,从1开始一次增加>
///修改描述:<对此修改的描述>
///作者:修改者中文名
///修改日期:<模块修改日期,格式:YYYY-MM-DD>
///</summary>
3.2 类属性注释规范
在类的属性必须以以下格式编写属性注释:
/// <summary>
///属性说明
/// </summary>
3.3 方法注释规范
在类的方法声明前必须以以下格式编写注释
/// <summary>
/// 说明:<对该方法的说明>
/// </summary>
/// <param name="<参数名称>"><参数说明></param>
/// <returns>
///<对方法返回值的说明,该说明必须明确说明返回的值代表什么含义>
/// </returns>
3.4 代码间注释规范
代码间注释分为单行注释和多行注释:
单行注释:
//<单行注释>
多行注释:
/*多行注释1
多行注释2
多行注释3*/
代码行数太多而不容易区分时注释:
/******************************************
* 代码块功能名称
******************************************/
//<单行注释>
或
/*多行注释1
多行注释2*/
或者也可以使用下面方法:
/********* 代码块功能名称开始 ************/
//<单行注释>
//<单行注释>
/********* 代码块功能名称结束 ************/
注释说明
A. 代码中遇到语句块时必须添加注释(if,for,foreach,……),添加的注释必须能够说明此语句块的作用和实现手段(所用算法等等)。 对一个数值变量采用不是0,-1等的数值初始化,给出选择该值的理由。
B. 尽量多点注释,就算能一目了然的命名最好也顺便写一写注释,方便以后接收的人能更容易理解程序(方便不太懂英文的程序员)。
C. 如果因为某种原因使用了复杂艰涩的原理,为程序配备良好的文档和更多的注释。
4. 编码规范
1)缩进和间隔:缩进用TAB,不用 SPACES。
2)注释需和代码对齐。多使用#regedit和#endregion代码块。
3)在代码中垂直对齐左括号和右括号。
if (x == 0)
{
Response.Write("用户编号必须输入!");
}
不允许以下情况:
if(x == 0) {
Response.Write("用户编号必须输入!");
}
或者:
if(x == 0){ Response.Write("用户编号必须输入!"); }
4)适当的增加空行,来增加代码的可读性。
在下列情况下应该有两行空行:
同一文件的不同部分之间;
在类,接口以及彼此之间;
在下列情况之间应该有一行空行:
方法之间;
局部变量和它后边的语句之间;
方法内的功能逻辑部分之间;
5)避免使用大文件。如果一个文件里的代码超过300~400行,必须考虑将代码分开到不同类中。当然模板生成类与逻辑层类除外。
6)避免写太长的方法。一个典型的方法代码在1~25行之间。如果一个方法发代码超过25行,应该考虑将其分解为不同的方法。
7)为了防止在阅读代码时不得不滚动源代码编辑器,每行代码或注释在1024*768的显示频率下不得超过一显示屏
8)在大多数运算符之前和之后使用空格,这样做时不会改变代码的意图却可以使代码容易阅读。
例:
int j = i + k;
而不应写为
int j=i+k;
括号和它里面的字符之间不应该出现空格。括号应该和它前边的关键词留有空格。
例:
while (true)
{
};
但是方法名和左括号之间不应该有空格。
参数之间的逗号后应该加一空格。
例:
method1(int i1, int i2)
for语句里的表达式之间加一空格。
例:
for(expr1; expr2; expr3)
强制类型转换时,在类型和变量之间加一空格。
例:
(int) i ;
9)所有可供用户输入的字段值,必须需忽略前后空白后(不包含密码);在对字段值进行有效性验证。对提交进数据库的内容必须进行SQL注入过滤与XSS过滤。
10)一个方法只完成一个任务。不要把多个任务组合到一个方法中,即使那些任务非常小。
11)避免使用很多成员变量,声明局部变量,并传递给方法。
12)不要在方法间共享成员变量,如果在几个方法间共享一个成员变量,那就很难知道是哪个方法在什么时候修改了它的值。
13)不在代码中使用具体的路径和驱动器名,使用相对路径,并使路径可编程。永远别设想你的代码是在“C:”盘运行。你不会知道,一些用户在网络或“Z:”盘运行程序。
14)应用程序启动时作些“自检”并确保所需文件和附件在指定的位置。
如果需要的配置文件找不到,应用程序需能自己创建使用默认值的一份。如果在配置文件中发现错误值,应用程序要抛出错误,给出提示消息告诉用户正确值。
15)出现任何问题给用户一个友好的提示,错误消息需能帮助用户解决问题。
永远别用像“应用程序出错”,“发现一个错误”等错误消息。而应给出像“更新数据库失败,请确保登陆id和密码正确” 的具体消息。显示错误消息时,除了说哪里错了,还应提示用户如何解决问题。不要用像“更新数据库失败”这样的,要提示用户怎么做:“更新数据库失败,请确保登陆id和密码正确”
16)错误处理和异常事件
不要“捕捉了异常却什么也不做”。如果隐藏了一个异常,你将永远不知道异常到底发生了没有。
发生异常时,给出友好的消息给用户,但要精确记录错误的所有可能细节,包括发生的时间,和相关方法,类名等。
别写太大的 try-catch 模块。如果需要,为每个执行的任务编写单独的 try-catch 模块。 这将帮你找出哪一段代码产生异常,并给用户发出特定的错误消息
如果应用程序需要,可以编写自己的异常类。自定义异常不应从基类SystemException派生,而要继承于. IApplicationException。
作者:apegu
地址:http://www.cnblogs.com/jiangqw
如果,您认为阅读这篇博客让您有些收获,不妨点击一下推荐按钮。