C# 代码编写规范_c# 方法 书写规则

1、规范目的

以前写代码很随意的命名，现在在同事的带领下，认识到了自己在代码规范上的不足，花了两个星期的大力气来整理，以下是我一点的认识。

1）、一个软件的生命周期中，80%的花费在于维护；

2）、几乎没有任何一个软件，在其整个生命周期中，均由最初的开发人员来维护；

3）、编码规范可以改善软件的可读性，可以让程序员尽快而彻底地理解新的代码。为了执行规范，每个软件开发人员必须一致遵守编码规范；

4）、使用统一编码规范的主要原因，是使应用程序的结构和编码风格标准化，以便于阅读和理解这段代码；

5）、好的编码约定可使源代码严谨、可读性强且意义清楚，与其它语言约定相一致，并且尽可能的直观。

2、适用范围

1）、本规范主要以C#为开发语言的规范，为成都摩奇卡卡科技有限责任公司的原则性规范；

2）、由于本规范是为撰写程序而设计，所以适用于一切有关程序撰写的工作事项。对于具体的每个项目，可能需要对之进行裁剪和补充；

3）、适用人员：C#开发人员；

4）、适用产品：以C#编写的程序。

3、 代码注释

3.1、代码注释约定

1）、所有的文件、类、方法和函数都应该以描述这段代码的功能的一段简明注释开始（这段代码是干什么）。这种描述不应该包括执行过程细节（它是怎么做的），因为这常常是随时间而变的，而且这种描述会导致不必要的注释维护工作，甚至更糟—成为错误的注释。代码本身和必要的嵌入注释将描述实现方法。

2）、当参数的功能不明显且当过程希望参数在一个特定的范围内时，也应描述传递给过程的参数。被过程改变的函数返回 值和全局变量，特别是通过引用参数的那些，也必须在每个过程的起始处描述它们。

3.2 、模块头部注释规范

    以一个物理文件为单元的都需要有模块头部注释规范，例如：C#中的.cs文件

用于每个模块开头的说明，主要包括： 

I、文件名称(File Name)：此文件的名称

II、功能描述(Description)：此模块的功能描述与大概流程说明

III、数据表(Tables)：所用到的数据表，视图，存储过程的说明，如关系比较复杂，则应说明哪些是可擦写的，哪些表为只读的。

IV、作者(Author)：

V、日期(Create Date)：

VI、参考文档(Reference)(可选)：该档所对应的分析文档，设计文檔。

VII、引用(Using) (可选)﹕开发的系统中引用其它系统的Dll、对象时，要列出其对应的出处，是否与系统有关﹙不清楚的可以不写﹚，以方便制作安装档。

VIII、修改记录(Revision History)：若档案的所有者改变，则需要有修改人员的名字、修改日期及修改理由。

IX、分割符：*************************** (前后都要)

示例如下：

// ******************************************************

// 文件名（FileName）:               GlobalData.cs  

// 功能描述（Description）:          此文件用于处理订单的状态，以及合作商、服务器的配置信息。

// 数据表（Tables）:                 nothing

// 作者（Author）:                   Jordan Zuo

// 日期（Create Date）:              2014-03-03

// 修改记录（Revision History）:     

// ******************************************************

3.3 、方法注释规范

1）、 C# 提供一种机制，使程序员可以使用含有XML 文本的特殊注释语法为他们的代码编写文档。在源代码文件中，具有某种格式的注释可用于指导某个工具根据这些注释和它们后面的源代码元素生成XML。具体应用当中，类、接口、属性、方法必须有<Summary>节，另外方法如果有参数及返回值，则必须有<Param>及<Returns>节。示例如下：

/// <summary>

/// 初始化合作商列表

/// </summary>

/// <param name="partnerID">合作商ID</param>

/// <returns>合作商信息</returns>

2）、事件不需要头注解，但包含复杂处理时（如：循环/数据库操作/复杂逻辑等），应分割成单一处理函数，事件再调用函数。

3）、所有的方法必须在其定义前增加方法注释。

4）、方法注释采用 /// 形式自动产生XML标签格式的注释。

5）、 在公用类库中的公用方法需要在一般方法的注释后添加作者、日期及修改记录信息，统一采用XML标签的格式加注，标签如下：

<Author>作者</Author> 

　　<CreateDate>建立日期</CreateDate> 

　　<RevisionHistory> 修改记录

　　　　<ModifyBy>修改作者</ModifyBy>

　　　　<ModifyDate>修改日期</ModifyDate> 

<ModifyReason><修改理由/ModifyReason> 

 

　　　　<ModifyBy>修改作者</ModifyBy>

　　　　<ModifyDate>修改日期</ModifyDate> 

<ModifyReason><修改理由/ModifyReason>

</RevisionHistory>

<LastModifyDate>最后修改日期</LastModifyDate> 

6）、 一个代码文件如果是由一人编写，则此代码文件中的方法无需作者信息，非代码文件作者在此文件中添加方法时必须要添加作者、日期等注释。

7）、 修改任何方法，必须要添加修改记录的注释。

3.4 、代码行注释规范

1）、 如果处理某一个功能需要很多行代码实现，并且有很多逻辑结构块，类似此种代码应该在代码开始前添加注释，说明此块代码的处理思路及注意事项等。

　　2）、注释从新行增加，与代码开始处左对齐。

3）、双斜线与注释之间以空格分开，示例图如下所示：

/// <summary>

        /// 输出结果

        /// </summary>

        /// <param name="result">结果对象</param>

        protected void ResponseResult(ReturnObject result)

        {

            try

            {

                //JSON化

                String jsonResult = JsonUtil.Serialize(result);

 

                //输出到客户端

                System.Web.HttpContext.Current.Response.Write(jsonResult);

                System.Web.HttpContext.Current.Response.End();

            }

            catch (Exception ex)

            {

                LogUtil.Write(ex.StackTrace == null ? ex.Message : ex.StackTrace + Environment.NewLine + ex.Message, LogType.Error);

            }

   }

 

3.5 、变量注释规范

1）、定义变量时需添加变量注释，用以说明变量的用途。

2）、 Class级变量应以采用 /// 形式自动产生XML标签格式的注释，示例图如下所示：

/// <summary>

    /// 类名称，用于错误标识

    /// </summary>

private static String mClassName;

 

3）、方法级的变量注释可以放在变量声明语句的后面，与前后行变量声明的注释左对齐，注释与代码间以Tab隔开；也可以写在变量的上边；如下代码所示：

/// <summary>

        /// 获取合作商对象

        /// </summary>

        /// <param name="partnerID">合作商ID</param>

        /// <returns>合作商对象</returns>

        internal static PartnerDB GetPartnerItem(Int32 partnerID)

        {

Dictionary<Int32, PartnerDB> partnerList;  //合作商列表

 

             //获取合作商列表

partnerList = GetPartnerList();

 

            //判断是否存在

            if (!partnerList.ContainsKey(partnerID)) return null;

 

            return partnerList[partnerID];

}

 

4 、命名规则

4.1 、命名的基本约定

1）、要使用可以准确说明变量/字段/类的完整的英文描述符，如firstName。对一些作用显而易见的变量可以采用简单的命名，如在循环里的递增（减）变量就可以被命名为 “i”。

2）、 要尽量采用项目所涉及领域的术语。

3）、 要采用大小写混合，提高名字的可读性。为区分一个标识符中的多个单词，把标识符中的每个单词的首字母大写。不采用下划线作分隔字符的写法。

有两种适合的书写方法，适应于不同类型的标识符：

PasalCasing：标识符的第一个单词的字母大写；

camelCasing：标识符的第一个单词的字母小写。

4）、下表描述了不同类型标识符的大小写规则：

5）、避免使用缩写，如果一定要使用，就谨慎使用。同时，应该保留一个标准缩写的列表，并且在使用时保持一致。

6）、对常见缩略词，两个字母的缩写要采用统一大小写的方式（示例：ioStream，getIOStream）；多字母缩写采用首字母大写，其他字母小写的方式（示例：　　　　getHtmlTag）；

7）、避免使用长名字（最好不超过 15 个字母）；

8）、避免使用相似或者仅在大小写上有区别的名字。

4.2 、各种标示符类型的命名约定

1）、程序集命名

　　公司名称（Company）+ 项目名称 + 模块名称（可选），例如：

　　　　ManageCenter服务器程序集：Company. ManageCenter；

　　　　数据代理服务器程序集：Company.DataProxy；

　　2）、 命名空间命名

　　采用和程序集命名相同的方式：公司名称（Company）+ 项目名称 + 模块名称。 另外，一般情况下建议命名空间和目录结构相同。例如：

　　　　ManageCenter服务器：Company. ManageCenter；

　　　　数据代理服务器：Company.DataProxy； 

　　3）、程序集和DLL

大多数情况下，程序集包含全部或部分可重用库，且它包含在单个动态链接库(DLL) 中。

　　一个程序集可拆分到多个DLL 中，但这非常少见，在此准则中也没有说明。

　　程序集和DLL 是库的物理组织，而命名空间是逻辑组织，其构成应与程序集的组织无关。

　　命名空间可以且经常跨越多个程序集。可以考虑如下模式命名DLL：

        <Company>.<Component>.dll

   　　     例：Company. ManageCenter.dll

　　4）、类和接口命名

I、类的名字要用名词；

II、避免使用单词的缩写，除非它的缩写已经广为人知，如HTTP；

III、接口的名字要以字母I开头。保证对接口的标准实现名字只相差一个“I”前缀，例如对IComponent接口的标准实现为Component；

IV、泛型类型参数的命名：命名要为T或者以T开头的描述性名字，例如：

　　　　public class List<T>

　　　　public class MyClass<Tsession>

V、对同一项目的不同命名空间中的类，命名避免重复。避免引用时的冲突和混淆；

　　5）、方法命名

　　I、第一个单词一般是动词；

　　II、如果方法返回一个成员变量的值，方法名一般为Get+成员变量名，如若返回的值是bool变量，一般以Is作为前缀。另外，如果必要，考虑用属性来替代方法；

　　III、如果方法修改一个成员变量的值，方法名一般为：Set + 成员变量名。同上，考虑用属性来替代方法。

　　6）、 变量命名

　　I、按照使用范围来分，我们代码中的变量的基本上有以下几种类型，类的公有变量、类的私有变量（受保护同公有）、方法的参数变量、方法内部使用的局部变量。这些变量的命名规则基本相同，见标识符大小写对照表。区别如下：

　　　　A）、类的公有变量按通常的方式命名，无特殊要求；

　　　　B）、类的私有变量采用两种方式均可：采用加“m”前缀，例如mWorkerName;

　　　　C）、方法的参数变量采用camalString，例如workerName；

　　II、方法内部的局部变量采用camalString，例如workerName。

　　III、不要用_或&作为第一个字母；

　　IV、尽量要使用短而且具有意义的单词；

　　V、单字符的变量名一般只用于生命期非常短暂的变量：i,j,k,m,n一般用于integer；c,d,e 一般用于characters；s用于string；

　　VI、如果变量是集合，则变量名要用复数。例如表格的行数，命名应为：RowsCount；

VII、命名组件要采用匈牙利命名法，所有前缀均应遵循同一个组件名称缩写列表。

4.3 、组件名称缩写列表

缩写的基本原则是取组件类名各单词的第一个字母，如果只有一个单词，则去掉其中的元音，留下辅音。缩写全部为小写。

5、其它规范

5.1、编程风格

1）、变量声明：

　　为了保持更好的阅读习惯，请不要把多个变量声明写在一行中，即一行只声明一个变量。

　　例如：

　　String strTest1, strTest2;

　　应写成：

　　String strTest1;

　　String strTest2;

2）、代码缩进：

　　I、 一致的代码缩进风格，有利于代码的结构层次的表达，使代码更容易阅读和传阅；

II、代码缩进使用Tab键实现，最好不要使用空格，为保证在不同机器上使代码缩进保持一致，特此规定C#的Tab键宽度为4个字符；

III、避免方法中有超过5个参数的情况，一般以2,3个为宜。如果超过了，则应使用struct来传递多个参数；

　　lV、为了更容易阅读，代码行请不要太长，最好的宽度是屏幕宽度（根据不同的显示分辩率其可见宽度也不同）。请不要超过您正在使用的屏幕宽度。（每行代码不要超过80个字符）；

V、程序中不应使用goto语句；

VI、在switch语句中总是要default子句来显示信息；

VII、操作符/运算符左右空一个半角空格。

3）空白：

I、空行将逻辑相关的代码段分隔开，以提高可读性。

II、下列情况应该总是使用一个空行：

　　　　a)  两个方法之间

　　　　b)  方法内的局部变量和方法的第一条语句之间

　　　　c)  块注释（#region）之前

　　　　d)  块注释（#region）与内部的代码之间

e)  一个方法内的两个逻辑段之间，用以提高可读性

III、下列情况应该总是使用空格：

　　　　a)  空白应该位于参数列表中逗号的后面，如：

　　　　　　void UpdateData(int a, int b)

　　　　b)  所有的二元运算符，除了"."，应该使用空格将之与操作数分开。一元操作符和操作数之间不因该加空格，比如：负号("-")、自增("++")和自减("--")。例如：

　　　　　　　　a += c + d;

　　　　　　　　d++;

　　　　c)  for 语句中的表达式应该被空格分开，例如：

　　　　　　　　for (expr1; expr2; expr3)

　　　　d)  强制转型后应该跟一个空格，例如：

　　　　　　　　char c;

　　　　　　　　int a = 1;

　　　　　　　　c = (char) a;

 

 

5.2 、资源释放

所有外部资源都必须显式释放。例如：数据库连接对象、IO对象等。

/// <summary>

        /// 释放资源

        /// </summary>

        public void Dispose()

        {

            //如果事务开启过，则释放事务

            if (this.IDbTrans != null)

            {

                this.IDbTrans.Dispose();

            }

 

            //如果连接已经打开，则关闭连接并释放资源

            if (this.IDbConn.State == ConnectionState.Open)

            {

                this.IDbConn.Close();

                this.IDbConn.Dispose();

            }

     }

5.3、错误处理

1）、不要“捕捉了异常却什么也不做“。如果隐藏了一个异常，你将永远不知道异常到底发生了没有。

2）、发生异常时，给出友好的消息给用户，但要精确记录错误的所有可能细节，包括发生的时间，和相关方法，类名等。

5.4、其它

1）、一个方法只完成一个任务。不要把多个任务组合到一个方法中，即使那些任务非常小。

　　2）、 使用System命名空间中定义类型，而不是C#自定义的别名类型。

　　3）、别在程序中使用固定数值，用常量或枚举代替。

　　4）、避免使用很多成员变量。声明局部变量，并传递给方法。不要在方法间共享成员变量。如果在几个方法间共享一个成员变量，那就很难知道是哪个方法在什么时候修改了它的值。

5）、别把成员变量声明为 public 或 protected。都声明为 private 而使用 public/protected 的属性。

　　6）、不在代码中使用具体的路径和驱动器名。 使用相对路径，并使路径可编程；

　　7）、应用程序启动时作些“自检”并确保所需文件和附件在指定的位置。必要时检查数据库连接。出现任何问题给用户一个友好的提示。

　　8）、如果需要的配置文件找不到，应用程序需能自己创建使用默认值的一份。

　　9）、如果在配置文件中发现错误值，应用程序要抛出错误，给出提示消息告诉用户正确值。

　　10）、DataColumn取其列时要用字段名，不要用索引号。
　　　　例： 正确DataColumn[“Name”]
    　　　　   不好DataColumn[0]

　　11）、在一个类中，字段定义全部统一放在class的头部、所有方法或属性的前面。

12）、在一个类中，所有的属性全部定义在一个属性块中，如下所示：

#region Properties

 

// Some Properties

 

#endregion

6、一些总结