《团队-排课软件-代码设计规范》

Posted 2020-10-08

C#代码编程规范

目录

第一章　概述.... 3

规范制定原则... 3

文件命名组织... 3

1.1文件命名... 3

1.2文件注释... 3

第二章 程序注释.... 5

2.1      注释概述... 5

2.2      文档型注释... 5

2.3      类注释... 6

2.4      函数注释... 6

2.5接口注释... 6

2.6      单行注释... 6

2.7      模块注释... 7

2.8方法注释... 7

2.9      变量注释... 8

第三章　命名规范.... 9

3.1命名概述... 9

3.2类... 9

3.3接口... 10

3.4静态变量... 10

3.5全局变量... 10

3.6 参数... 11

3.7 方法... 11

3.8字段... 11

3.9函数... 12

第一章　概述

 

规范制定原则

   1 方便代码的交流和维护。

   2 不影响编码的效率，不与大众习惯冲突,保证一致性统一性。

   3 使代码更美观、阅读更方便,代码可读性,并有助于代码管理。

   4 使代码的逻辑更清晰、更易于理解。

   5为了统一公司软件开发设计过程的编程规范

文件命名组织

1.1文件命名

1 文件名遵从Pascal命名法，无特殊情况，扩展名小写。

2 使用统一而又通用的文件扩展名： C# 类  .cs

3文件命名原则是更容易区分不同的文件类型，在文件名前增加三字符的前缀，前缀字母一律为小写

例如：

一个窗体文件可以增加frm前缀，frmForm1.cs

4文件主体名必须用名词或动名词，且主体名必须是单词首字大写的方式表示

例如：

证件登记的窗体可以命名为frmPatientReg.cs，一个取消证件登记的窗体可以命名为frmCancelPatientReg.cs

 

5文件名必须采用在不影响原意表达时尽量采用单词缩写的形式命名，以达到文件名的简洁明了的命名目的

 

1.2文件注释

  1 在每个文件头必须包含以下注释说明

            /*----------------------------------------------------------------

            // Copyright (C) 2012 科技集团

            // 版权所有。

            // 文件名：

            // 文件功能描述：          

            // 创建标识：

            // 创建描述

            // 修改标识：

            // 修改描述：

//----------------------------------------------------------------*/

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

 *      File:                                                                             *

 *                PermissionPrincipal.cs                                                 *

 *      Description:                                                                    *

 *                方法权限检测认证类                                   

 *      Author:                                                                          *

 *                qq                                                                     *                                                

 *      Finish DateTime:                                                                  *

 *               2012年2月28日                                                       *

 *      History:                                                                        *

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

文件功能描述只需简述。

创建标识和修改标识由创建或修改人员的名字、拼音或英文名加日期组成。

如：屈原/qu yuan2012年2月28日

一天内有多个修改的只需做一个在注释说明中做一个修改标识就够了。

在所有的代码修改处加上修改标识的注释。

 

第二章 程序注释

2.1   注释概述

1、修改代码时，总是使代码周围的注释保持最新。

2、在每个例程的开始，提供标准的注释样本以指示例程的用途、假设和限制很有帮助。注释样本应该是解释它为什么存在和可以做什么的简短介绍.

3、避免在代码行的末尾添加注释；行尾注释使代码更难阅读。不过在批注变量声明时，行尾注释是合适的；在这种情况下，将所有行尾注释在公共制表位处对齐。

4 、避免杂乱的注释，如一整行星号。而是应该使用空白将注释同代码分开。

5 、避免在块注释的周围加上印刷框。这样看起来可能很漂亮，但是难于维护。

6 、在部署发布之前，移除所有临时或无关的注释，以避免在日后的维护工作中产生混乱。

7 、如果需要用注释来解释复杂的代码节，请检查此代码以确定是否应该重写它。

尽一切可能不注释难以理解的代码，而应该重写它。尽管一般不应该为了使代码更简单以便于人们使用而牺牲性能，但必须保持性能和可维护性之间的平衡。

8 、在编写注释时使用完整的句子。注释应该阐明代码，而不应该增加多义性。

9 、在编写代码时就注释，因为以后很可能没有时间这样做。另外，如果有机会复查已编写的代码，在今天看来很明显的东西六周以后或许就不明显了。

10 、避免多余的或不适当的注释，如幽默的不主要的备注。

11、 使用注释来解释代码的意图。它们不应作为代码的联机翻译。

12、 注释代码中不十分明显的任何内容。

13 、为了防止问题反复出现，对错误修复和解决方法代码总是使用注释，尤其是在团队环境中。

14 、对由循环和逻辑分支组成的代码使用注释。这些是帮助源代码读者的主要方面。

15 、在整个应用程序中，使用具有一致的标点和结构的统一样式来构造注释。

16 、用空白将注释同注释分隔符分开。在没有颜色提示的情况下查看注释时，这样做会使注释很明显且容易被找到。

17 、在所有的代码修改处加上修改标识的注释。

18 、为了是层次清晰，在闭合的右花括号后注释该闭合所对应的起点。

    namespace Langchao.Procument.Web

{

} // namespace Langchao.Procument.Web

19 、典型算法必须有注释

2.2   文档型注释

 该类注释采用.Net已定义好的Xml标签来标记，在声明接口、类、方法、属性、字段都应该使用该类注释，以便代码完成后直接生成代码文档，让别人更好的了解代码的实现和接口。如

         ///<summary>MyMethod is a method in the MyClass class.

         ///<para>Here‘s how you could make a second paragraph in a description.

         ///<see cref="System.Console.WriteLine"/>

         ///for information about output statements.

         ///</para>

         ///<seealso cref="MyClass.Main"/>

         ///</summary>

   public static void MyMethod(int Int1)

   { }

2.3   类注释

  类属性注释
在类的属性必须以以下格式编写属性注释：
/// <summary>

///Class name 类名
/// <Properties depiction> 属性描述

/// Author   作者

/// Creation date 创建日期

/// Modified by修改者

/// Modified date 修改日期

/// Modify the description  修改描述

/// Remarks   备注
/// </summary>
例如:

/// <summary>

/// Class name： 人员信息实体类层

/// depiction： 类层用于人员信息录入

/// Author ：qq

/// Creation date ：2012-3-5

/// Modified by ：qq

/// Modified date:2012-3-5

/// Modify the description:实体类层部分属性的添加 添加了一个属性

/// Remarks: 属性添加修改

 /// </summary>

    public class cls_Personnel

    {

    }

2.4   函数注释

标准的函数注释格式；
　　//==================================================================
　　//函数名： 
　　//作者： 
　　//日期： 
　　//功能： 
　　//输入参数：
　　//返回值： 
　　//修改记录：
　　//==================================================================
　　示例：
　　//==================================================================
　　//函数名： RecordIsExist
　　//作者： qq

　　//日期： 2012-03-05
　　//功能： 判断当前待插入或更新的记录在原表中是否已经存在
　　//输入参数：bm (表名） 待查找的 表的名字
　　// zdm (字段名）在表中待查找的字段
　　// zdz(字段值） 需要比较的字段的值
　　//返回值： 类型（boolean)
　　// 返回true表示当前表中存在一条跟待插入的记录一样的记录；
　　// 返回false表示当前待插入的记录在表中不存在。
　　//修改记录：
　　//==================================================================

 

2.5接口注释

接口只包含方法、委托或事件的签名。方法的实现是在实现接口的类中完成的，

/// <summary>

///  name：

/// depiction：

/// Author ：qq

/// Creation date ：2012-3-5

/// Modified by ：qq

/// Modified date:2012-3-5

/// Modify the description:

/// </summary>

public interface IComponent

 { }

2.6   单行注释

      该类注释用于

1 方法内的代码注释。如变量的声明、代码或代码段的解释。注释示例：

  //

// 注释语句

 //

private int number;

或

 // 注释语句

 private int number;

 2 方法内变量的声明或花括号后的注释, 注释示例：

               if ( 1 == 1)    // always true

               {   

                  statement;

                 } // always true

2.7   模块注释

模块开始必须以以下形式书写模块注释：
///<summary>
///Module ID：<模块编号，可以引用系统设计中的模块编号>
///Depiction：<对此类的描述，可以引用系统设计中的描述>
///Author：作者中文名
///Create Date：<模块创建日期，格式：YYYY-MM-DD>
///</summary>
如果模块只进行部分少量代码的修改时，则每次修改须添加以下注释：
///Modify Date：<修改日期:格式YYYY-MM-DD>Start1：
/* 原代码内容*/
///End1：
将原代码内容注释掉，然后添加新代码使用以下注释：
///Added by Add date：<添加日期，格式：YYYY-MM-DD>Start2：
///End2：
如果模块输入输出参数或功能结构有较大修改，则每次修改必须添加以下注释：
///<summary>
///Log ID：<Log编号,从1开始一次增加>
///depiction：<对此修改的描述>
///Author：修改者中文名
///Modify Date：<模块修改日期，格式：YYYY-MM-DD>
///</summary>

2.8方法注释

在类的方法声明前必须以以下格式编写注释
/// <summary>
/// depiction：<对该方法的说明>
/// </summary>
/// <paramname="<参数名称>"><参数说明></param>
/// <returns>
///<对方法返回值的说明，该说明必须明确说明返回的值代表什么含义>
/// </returns>
///Author：作者中文名
///Create Date：<方法创建日期，格式：YYYY-MM-DD>

/// <summary>

        /// depiction：绑定信息

        /// Author： qq 2012.2.28

        /// </summary>

        /// <param name="cls">参数cls</param>

        /// <param name="RecordCount">返回记录</param>

        /// <returns>返回记录</returns>

public override ArrayList ApproveList_NotCommit(cls_Approve cls, out int RecordCount)

        {

}

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

         <Author></Author> 作者

        <CreateDate></CreateDate> 建立日期

         <RevisionHistory> 修改记录

         <ModifyBy></ModifyBy>       修改作者

         <ModifyDate></ModifyDate> 修改日期

         <ModifyReason></ModifyReason>         修改理由

        

        <ModifyBy></ModifyBy>        修改作者

         <ModifyDate></ModifyDate> 修改日期

         <ModifyReason></ModifyReason>         修改理由

        

        <ModifyBy></ModifyBy>        修改作者

         <ModifyDate></ModifyDate> 修改日期

         <ModifyReason></ModifyReason>         修改理由

  </RevisionHistory>

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

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

 3修改任何方法，必须要添加修改记录的注释

2.9   变量注释

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

1. class级变量应以三条斜线的形式注释
2. 方法级的变量注释可以放在变量声明语句的后面，与前后行变量声明的注释左对齐，注释与代码间以Tab隔开。

第三章　命名规范

3.1命名概述

名称应该说明“什么”而不是“如何”。通过避免使用公开基础实现（它们会发生改变）的名称，可以保留简化复杂性的抽象层。例如，可以使用 GetNextStudent()，而不是 GetNextArrayElement()。

命名原则是：

选择正确名称时的困难可能表明需要进一步分析或定义项的目的。使名称足够长以便有一定的意义，并且足够短以避免冗长。唯一名称在编程上仅用于将各项区分开。表现力强的名称是为了帮助人们阅读；因此，提供人们可以理解的名称是有意义的。不过，请确保选择的名称符合适用语言的规则和标准。

以下几点是推荐的命名方法。

1、避免容易被主观解释的难懂的名称，如方面名 AnalyzeThis()，或者属性名 xxK8。这样的名称会导致多义性。

2、在类属性的名称中包含类名是多余的，如 Book.BookTitle。而是应该使用 Book.Title。

3、只要合适，在变量名的末尾或开头加计算限定符（Avg、Sum、Min、Max、Index）。

4、在变量名中使用互补对，如 min/max、begin/end 和 open/close。

5、布尔变量名应该包含 Is，这意味着 Yes/No 或 True/False 值，如 fileIsFound。

6、在命名状态变量时，避免使用诸如 Flag 的术语。状态变量不同于布尔变量的地方是它可以具有两个以上的可能值。不是使用 documentFlag，而是使用更具描述性的名称，如 documentFormatType。 （此项只供参考）

7、即使对于可能仅出现在几个代码行中的生存期很短的变量，仍然使用有意义的名称。仅对于短循环索引使用单字母变量名，如 i 或 j。 可能的情况下，尽量不要使用原义数字或原义字符串，如

For i = 1 To 7。而是使用命名常数，如 For i = 1 To NUM_DAYS_IN_WEEK 以便于维护和理解。

为一个名称空间名。

  

3.2类

1、使用 Pascal 大小写。

2、用名词或名词短语命名类。

3、使用全称避免缩写，除非缩写已是一种公认的约定，如URL、html   

4 、不要使用类型前缀，如在类名称上对类使用 C 前缀。例如，使用类名称 FileStream，而不是

CFileStream。

5 、不要使用下划线字符 (_)。

6 、有时候需要提供以字母 I 开始的类名称，虽然该类不是接口。只要 I 是作为类名称组成部分的整个单词的第一个字母，这便是适当的。例如，类名称 IdentityStore 是适当的。在适当的地方，使用复合单词命名派生的类。派生类名称的第二个部分应当是基类的名称。例如，ApplicationException 对于从名为 Exception 的类派生的类是适当的名称，原因ApplicationException 是一种Exception。请在应用该规则时进行合理的判断。例如，Button 对于从 Control 派生的类是适当的名称。尽管按钮是一种控件，但是将 Control 作为类名称的一部分将使名称不必要地加长。

 

            public class FileStream

            public class Button

            public class String

 

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

public class List<T>

public class MyClass<TSession>

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

 

3.3接口

      以下规则概述接口的命名指南：

      1、用名词或名词短语，或者描述行为的形容词命名接口。例如，接口名称 IComponent 使用描述性

名词。接口名称 ICustomAttributeProvider 使用名词短语。名称 IPersistable 使用形容词。

2、使用 Pascal 大小写。

      3、少用缩写。

4、给接口名称加上字母 I 前缀，以指示该类型为接口。在定义类/接口对（其中类是接口的标准

实现）时使用相似的名称。两个名称的区别应该只是接口名称上有字母 I 前缀。

 

5、不要使用下划线字符 (_)。

6、当类是接口的标准执行时，定义这一对类/接口组合就要使用相似的名称。两个名称的不同之处

只是接口名前有一个I前缀。

 

          以下是正确命名的接口的示例。

                public interface IServiceProvider

                public interface IFormatable

          以下代码示例阐释如何定义 IComponent 接口及其标准实现 Component 类。

               public interface IComponent

               {

                   // Implementation code goes here.

               }

                   public class Component: IComponent

               {

                   // Implementation code goes here.

               }

3.4静态变量

全局变量/静态变量定义全部要大写 如：

Public static  int  SMS_TYPE=2;

定义部分也可以大小写。

如：public static string  VOSMS_UserName=”000000”

单词与单词之间加“-”分隔符

静态变量前加s_(表示static

例如：

        Void init (…)

     Static int s_initValue;//静态变量

3.5全局变量

使用全局变量加前缀g_(表示global)

例如

Int g_howManyPeople;//全局变量

String UserName

3.6 参数

       以下规则概述参数的命名指南：

           1、使用描述性参数名称。参数名称应当具有足够的描述性，以便参数的名称及其类型可用于在大多数情况下确定它的含义。

       2、对参数名称使用 Camel 大小写。

           3、 使用描述参数的含义的名称，而不要使用描述参数的类型的名称。开发工具将提供有关参数的类型的有意义的信息。因此， 通过描述意义，可以更好地使用参数的名称。少用基于类型的参数名称，仅在适合使用它们的地方使用它们。

           4、不要使用保留的参数。保留的参数是专用参数，如果需要，可以在未来的版本中公开它们。相反，如果在类库的未来版本中需要更多的数据，请为方法添加新的重载。

           5、不要给参数名称加匈牙利语类型表示法的前缀。

       以下是正确命名的参数的示例。

               Type GetType(string typeName)

string Format(string format, args() As object)

 

3.7 方法

 以下规则概述方法的命名指南：

  1 使用动词或动词短语命名方法。方法名的主体应该使用大小写混合形式，并且应该足够长以描述它的作用。而且，方法名应该以一个动词起首，如 InitNameArray 或 CloseDialog。

对于频繁使用的或长的项，推荐使用标准缩略语以使名称的长度合理化。一般来说，超过 32 个字符的变量名在 VGA 显示器上读起来就困难了。

当使用缩略语时，要确保它们在整个应用程序中的一致性。在一个工程中，如果一会儿使用 Cnt， 一会儿使用 Count，将导致不必要的混淆。

 

           2 使用 Pascal 大小写。

           3 以下是正确命名的方法的实例。

              RemoveAll()

              GetCharArray()

Invoke()

3.8字段

        以下规则概述字段的命名指南：

            1、private、protected 使用 Camel 大小写。

            2、public 使用 Pascal 大小写。

3、拼写出字段名称中使用的所有单词。仅在开发人员一般都能理解时使用缩写。字段名称不

要使用大写字母。下面是正确命名的字段的示例。

         class SampleClass

                {

                    string url;

             string destinationUrl;

           }

 4、不要对字段名使用匈牙利语表示法。好的名称描述语义，而非类型。

5、不要对字段名或静态字段名应用前缀。具体说来，不要对字段名称应用前缀来区分静态和非静态字段。例如，应用 g_ 或 s_ 前缀是不正确的。

6、对预定义对象实例使用公共静态只读字段。如果存在对象的预定义实例，则将它们声明为

对象本身的公共静态只读字段。使用 Pascal 大小写，原因是字段是公共的。下面的代码

示例阐释公共静态只读字段的正确使用。

                  public struct Color

                  {

                      public static readonly Color Red = new Color(0x0000FF);

                      public Color(int rgb)

{

 // Insert code here.}

                          public Color(byte r, byte g, byte b)

                          {

// Insert code here.

                           }

                      public byte RedValue

                      {

                           get

                           {

                                return Color;

                           }

                       }

                   }

     静态字段  以下规则概述静态字段的命名指南：

           1、使用名词、名词短语或者名词的缩写命名静态字段。

           2、使用 Pascal 大小写。

           3、对静态字段名称使用匈牙利语表示法前缀。

           4、建议尽可能使用静态属性而不是公共静态字段。

3.9函数

用大写字母开头的单词组合以动词为开始或者 动词+名词，每个单词第一个字母必须大写。单词之间不加“-”。

例如：

Public static string GetOrderStatus(int  sendMode, int  statusID)

函数名和方法名以动词开始 如：intNameArray() 和CloseDialog().

构造函数的名字与类同名 无返回值类型(这与返回值类型为void的函数不同)