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=newUsers();

Users model=newUsers();

Users userModel=newUsers();

const string const_String = "";(不同公司有不同的约定,具体根据自己公司情况设置而定)

 

      Private stringGetProductName(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。

 

你可能感兴趣的:(框架,设计)