【心得】我的C#开发规范

白露 — Fri, 28 Apr 2017 07:00:06 +0000

声明：

全文整理自互联网。本人只是根据个人习惯做了适量修改_(:з」∠)_

来源：

unity3D 之C#命名规则与风格

C# 命名规范作者：qq617119142

非常感谢！_(:з」∠)_

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 以便于维护和理解。

大小写规则

大写标识符中的所有字母都大写。仅对于由两个或者更少字母组成的标识符使用该约定。例如：

System.IO
System.Web.UI

下表汇总了大写规则，并提供了不同类型的标识符的示例。

缩写规范

为了避免混淆和保证跨语言交互操作，请遵循有关区缩写的使用的下列规则：

1.标识符应当直观可望文知意，不提倡使用任何缩写。

2.缩写可自行定义，一般取单词的前/后字符组成，以含义直观为准则。

3.字符串变量推荐是用“str”或“sz”开头，采用Empty来初始化。

4.普通对象可以以“obj”开头。

5.一般情况下不要让缩写破坏标识符的含义。不要使用计算机领域中未被普遍接受的缩写。

6.不要将缩写或缩略形式用作标识符名称的组成部分。例如，使用 GetWindow，而不要使用 GetWin。

7.在适当的时候，使用众所周知的缩写替换冗长的词组名称。例如，用 UI 作为 User Interface 缩写，用 OLAP 作为 On-line Analytical Processing 的缩写。

8.在使用缩写时，对于超过两个字符长度的缩写请使用 Pascal 大小写或 Camel 大小写。例如，使用 HtmlButto或 HTMLButton。但是，应当大写仅有两个字符的缩写，如，System.IO，而不是 System.Io。

9.不要在标识符或参数名称中使用缩写。如果必须使用缩写，对于由多于两个字符所组成的缩写请使用Camel 大小写，虽然这和单词的标准缩写相冲突。

1.1 文件

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

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

C# 类 .cs

1.2 类

1.使用Pascal规则命名类名，即首字母要大写。

Class Test
{
   ...
}

2.使用能够反映类功能的名词或名词短语命名类。

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

4.不要使用“I”．“C”．“_”等特定含义前缀。

5.自定义异常类应以Exception结尾。

Class TestException
{
    ...
}

文件名要能反映类的内容，最好是和类同名。

1.3 类字段 (类成员)

1.用camel规则来命名类成员变量名。

2.坚决禁止在普通变量前加“m_”（这是VC老命名规则）。

3.private、protected 使用 camel 大小写。

4.public 使用 Pascal 大小写。

Class Test
{
    private string myName;
    public string HisName;
    ...
}

5.拼写出字段名称中使用的所有单词。仅在开发人员一般都能理解时使用缩写。字段名称不要使用大写字母。下面是正确命名的字段的示例。

class SampleClass
{
    string url;
    string destinationUrl;
}

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

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

8.对预定义对象实例使用公共静态只读字段。如果存在对象的预定义实例，则将它们声明为对象本身的公共静态只读字段。使用 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.4 静态字段

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

2.使用 Pascal 大小写。

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

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

1.5 集合

集合是一组组合在一起的类似的类型化对象，如哈希表、查询、堆栈、字典和列表，集合的命名建议用复数。

1.6 方法

1.方法名采用Pascal规则，第一个字符要大写。

2.方法名应使用动词或动词短语。

3.类中访问修饰符或功能相同的方法应该放在一起，且公共或实现接口的方法在前。

Class Test
{
     ...
     public void GetData(...)
     {
         ...
     }
 
     private void GetName(...)
     {
         ...
     }
     
     private static void GetCount(...)
     {
        ...
     }
}

1.7 属性

1.使用名词定义属性，属性使用Pascal规则，首字符大写。

2.属性和相应字段名称要关联，即将字段名首字母变大写，可以使用“重构”菜单来生成属性。

Class Test
{
    private string myName;
    public string MyName
    {
        set
        {
            myName = Value;
        }
        get
        {
           return myName;
        }
    }
}

1.8 参数

1.参数采用camel规则命名，且首字符小写。

2.不要给参数加匈牙利语类型表示法的前缀。

3.检查方法所有输入参数的有效性。

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

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

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

ClassTest
{
    public void GetData(string name, string strFlag)
    {
        ...
    }
}

1.9 常量

1.枚举名使用Pascal规则命名，枚举成员本质属于常量，命名规则同上。

2.枚举值从小到大顺序定义。

3.所有单词大写，多个单词之间用 “_” 隔开。如

public const string PAGE_TITLE = "Welcome";

1.10 枚举(Enum)

枚举 (Enum) 值类型从 Enum 类继承。以下规则概述枚举的命名指南：

1.对于 Enum 类型和值名称使用 Pascal 大小写，并在其开头加上“E”。

2.少用缩写。

3.不要在 Enum 类型名称上使用 Enum 后缀。

4.对大多数 Enum 类型使用单数名称，但是对作为位域的 Enum 类型使用复数名称。

5.总是将 FlagsAttribute 添加到位域 Enum 类型。

1.11 接口

1.接口定义使用Pascal规则，且必须以大写“I”开头。

2.接口名称要有意义，中间不要有下划线“_”等字符。

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

4.少用缩写。

5.给接口名称加上字母 I 前缀，以指示该类型为接口。在定义类/接口对（其中类是接口的标准实现）时使用相似的名称。两个名称的区别应该只是接口名称上有字母 I 前缀。

3.如果类实现了接口，名称尽量和接口相同，只是省掉“I”字符。

(注意这里的接口修饰符只能用public和internal)

interfaceITest
{
   ...
}

7.当类是接口的标准执行时，定义这一对类/接口组合就要使用相似的名称。两个名称的不同之处只是接口名前有一个I前缀。

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

public interface IServiceProvider;

public interface IFormatable;

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

public interface IComponent
{
    // Implementation code goes here.
}

public class Component: IComponent
{
    // Implementation code goes here.
}

1.12 事件

1.委托名称采用Pascal规则，即首字符大写。

2.定义事件的委托要使用EventHandler后缀，且包括sender和e两个参数。

sender 参数表示引发事件的对象。sender 参数始终是object 类型的，即使在可以使用更为特定的类型时也如此。与事件相关联的状态封装。在名为 e 的事件类的实例中。对 e 参数类型使用适当而特定的事件类。

3.事件用到的参数，名称要带EventArgs后缀。

ClassTest
{
    private delegate void DoTask();
    private event DoTask DoTaskEventHandler;
    private event DoTask DoTaskEventHandler(Object sender,EventArgse);
    private event DoTaskDoTaskEventHandler2(string   strEventArgs)
    {
       ...
    }
    ...
}

4.考虑用动词命名事件。

5.使用动名词（动词的“ing”形式）创建表示事件前的概念的事件名称，用过去式表示事件后。例如，可以取消的 Close 事件应当具有 Closing 事件和 Closed 事件。不要使用BeforeXxx/AfterXxx 命名模式。

6.不要在类型的事件声明上使用前缀或者后缀。例如，使用 Close，而不要使用 OnClose。

7.通常情况下，对于可以在派生类中重写的事件，应在类型上提供一个受保护的方法（称为OnXxx）。此方法只应具有事件参数 e，因为发送方总是类型的实例。

以下示例阐释具有适当名称和参数的事件处理程序:

public delegate void MouseEventHandler(object sender, MouseEventArgs e);

以下示例阐释正确命名的事件参数类:

public class MouseEventArgs : EventArgs
{
    int x;
    int y;

    public MouseEventArgs(int _x, int _y)
    {
        x = _x;
        y = _y;
    }
    public int X
    {
        get
        {
            return x;
        }
    }
 
    public int Y
    {
        get
        {
            return y;
        }
    }
}

1.13 命名空间

1.命名空间名称采用Pascal规则，且首字符大写。

2.命名空间名称尽量反映其内容所提供的整体功能。

namespace MyTest
{
    ClassTest
    {
       ...
    }
    ...
}

3.命名命名空间时的一般性规则是使用公司名称，后跟技术名称和可选的功能与设计，如下所示。

CompanyName.TechnologyName[.Feature][.Design]

例如：

namespace Langchao.Procurement             //浪潮公司的采购单管理系统

namespace Langchao.Procurement.DataRules   //浪潮公司的采购单管理系统的业务规则模块

4.TechnologyName 指的是该项目的英文缩写，或软件名。

5.命名空间和类不能使用同样的名字。

例如，有一个类被命名为Debug后，就不要再使用Debug作为一个名称空间名。

2．注释规范

2.1 文件头部注释

1.文件都包含文件头，要说明文件名．作者．创建时间．变更记录。

2.推荐采用.NET形式书写头部注释。(待考查)

/*----------------------------------------------------------------
// Copyright (C) 2017 软件有限公司
// 版权所有。
//
// 文件名：
// 文件功能描述：
//
//
// 创建标识：
//
// 修改标识：
// 修改描述：
//
// 修改标识：
// 修改描述：
//----------------------------------------------------------------*/

3.文件功能描述只需简述，具体详情在类的注释中描述。

4.创建标识和修改标识由创建或修改人员的拼音或英文名加日期组成。如：

Norvi 2017/4/28

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

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

2.2 类及其成员注释

1.对方法和类使用“///”三斜线注释。

2.字段用“//”行尾注释。

3.解释某一行代码功能在其前一行“//”注释。

4.代码行文注释采用“//”和“/**/”进行，应该尽量说明问题。

2.3 其他

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

///
MyMethod is a method in the MyClass class.
///Here's how you could make a second paragraph in a description.
///
///for information about output statements.
///
///
///

public static void MyMethod(int Int1)
{
        …
}

3．行文规范

3.2 排版

1. 每行语句至少占一行，如果语句过长（超过一屏），则该语句断为两行显示。

2.把相似的内容放在一起，比如字段．属性．方法．事件等，使用“#region–#endregion”命令分组。

3.多个程序元素进行对等操作时，操作符之前．之后或者前后都要加空格。

4.每个方法的源程序行数原则上应该少于200行。(如果超过过多，则需要另写一方法)

5.语句嵌套层次不得超过3层。

6.避免相同的代码段在多个地方出现。(尽量避免代码重复，能复用则复用)

7.列宽代码列宽控制在110字符左右。

8.换行当表达式超出或即将超出规定的列宽，遵循以下规则进行换行:

1．在逗号后换行。

2．在操作符前换行。

3．规则1优先于规则2。

（当以上规则会导致代码混乱的时候自己采取更灵活的换行规则。）

9.缩进缩进应该是每行一个Tab(4个空格)，不要在代码中使用Tab字符。

Visual Studio.Net设置：工具->选项->文本编辑器->C#->制表符->插入空格

10.空行空行是为了将逻辑上相关联的代码分块，以便提高代码的可阅读性。

11.在以下情况下使用两个空行:

1．接口和类的定义之间。

2．枚举和类的定义之间。

3．类与类的定义之间。

12.在以下情况下使用一个空行:

1．方法与方法．属性与属性之间。

2．方法中变量声明与语句之间。

3．方法与方法之间。

4．方法中不同的逻辑块之间。

5．方法中的返回语句与其他的语句之间。

6．属性与方法．属性与字段．方法与字段之间。

7．注释与它注释的语句间不空行，但与其他的语句间空一行。

13.空格在以下情况中要使用到空格:

关键字和左括符“(”应该用空格隔开。如

while (true)

注意在方法名和左括符“(”之间不要使用空格，这样有助于辨认代码中的方法调用与关键字。

14.多个参数用逗号隔开，每个逗号后都应加一个空格。

15.除了.之外，所有的二元操作符都应用空格与它们的操作数隔开。一元操作符．++及–与操作数间不需要空格。

a += c + d;
a = (a + b) / (c * d);

while (d++ = s++)
{
    n++;
}
PrintSize(“size is “ + size + “\n”);

16.语句中的表达式之间用空格隔开。如

for (expr1; expr2; expr3)

括号- ()

1.左括号“(”不要紧靠关键字，中间用一个空格隔开。

2.左括号“(”与方法名之间不要添加任何空格。

3.没有必要的话不要在返回语句中使用()。如

if (condition)
    Array.Remove(1);
return 1;

花括号- {}

1.左花括号“{”放于关键字或方法名的下一行并与之对齐。如

if (condition)
{
    ...
}
public int Add(int _x, int _y)
{
    ...
}

2.左花括号“{”要与相应的右花括号“}”对齐。

3.通常情况下左花括号“{”单独成行，不与任何语句并列一行。

4.if．while．do语句后一定要使用{}，即使{}号中为空或只有一条语句。如

if (somevalue == 1)
{
    somevalue = 2;
}

5.右花括号“}”后建议加一个注释以便于方便的找到与之相应的{。如

while (1)
{
    if (valid)
    {
        ...
    } // if valid
    else
    {
        ...
    } // not valid
} // end forever

3.3 语句结构

1.如果使用了异常结构，一定要处理异常，一般是要写日志文件。

2.分支语句不应该使用复杂长条件，应该将长条件封装成方法。

3.switch语句，case后面必须接break。

4.禁止使用goto语句进行跳转。

5.行文中严禁出现“魔数”，特定含义的常数必须定义成枚举或常量。

6.不同类型的操作符混合使用时，使用括号给出优先级。

7.不允许使用复杂的操作符组合等。

8.循环．判断语句的程序块部分用花括号括起来，即使只有一条语句。(return;待议)

9.在switch语句中总是要有default字句，建议使用断言。

10.每个类和方法完成单一的功能，不设计多用途面面俱到的类或方法。

11.严禁使用未经初始化的变量，变量通常使用构造方法来初始。

3.4 声明

1.每行声明数一行只建议作一个声明，并按字母顺序排列。如

int level;   //推荐
int size;    //推荐
int x, y;    //不推荐

2.初始化建议在变量声明时就对其做初始化。

3.位置变量建议置于块的开始处，不要总是在第一次使用它们的地方做声明。如

void MyMethod()
{
    int int1 = 0;         // beginning of method block
    if (condition)
    {
        int int2 = 0;     // beginning of "if" block
        ...
    }
}

不过也有一个例外

for (int i = 0; i < maxLoops; i++)
{
    ...
}

4.应避免不同层次间的变量重名，如

int count;
...
void MyMethod()
{
    if (condition)
    {
         int count = 0;     //避免
         ...
    }
    ...
}

类和接口的声明

1．在方法名与其后的左括号间没有任何空格。

2．左花括号“{”出现在声明的下行并与之对齐，单独成行。

3．方法间用一个空行隔开。

字段的声明

不要使用是public或protected的实例字段。如果避免将字段直接公开给开发人员，可以更轻松地对类进行版本控制，原因是在维护二进制兼容性时字段不能被更改为属性。考虑为字段提供get和set属性访问器，而不是使它们成为公共的。get和set属性访问器中可执行代码的存在使得可以进行后续改进，如在使用属性或者得到属性更改通知时根据需要创建对象。下面的代码示例阐释带有get和set属性访问器的私有实例字段的正确使用。示例：

public class Control: Component
{
    private int handle;
    public int Handle
    {
        get
        {
            return handle;
        }
    }
}

3.5 大小写

1.不要创建名称相同，但大小写区别的任何元素。

2.应当大写仅有两个字符的缩写。(如果只有两个字符，则都大写)

3.不要把易混淆的数字和字符放在一起。

4.使用英文命名标识符。

3.6 重名规范

不允许变量名．类名．属性名．方法名等与系统标识符重名。

3.7 SQL编码规范

1.SQL语句全部大写。

2.对较为复杂的SQL语句加上注释，说明其功能。

3.连接符OR．IN．AND．以及=．<=．>=等前后加空格。

4.使用明确的列代替 SELECT *。

3.8 语句格式

1.每行最多包含一个语句。如

a++;       //推荐
b--;       //推荐
a++; b--;   //不推荐

2.复合语句复合语句是指包含”父语句{子语句;子语句;}”的语句，使用复合语句应遵循以下几点

1．子语句要缩进。

2．左花括号“{” 在复合语句父语句的下一行并与之对齐，单独成行。

3．即使只有一条子语句要不要省略花括号“ {}”。如

while (d + =  s++)
{
    n++;
}

return语句

return语句中不使用括号，除非它能使返回值更加清晰。如

return;
return myDisk.size();
return (size ? size : defaultSize);

if、 if-else、if else-if 语句

if语句使用格式：

if (condition)
{
    statements;
}

if-else语句使用格式：

if (condition)
{
    statements;
}
else
{
    statements;
}
        /*-------空行--------*/
if (condition2)
{
    statements2;
}

if else-if 语句使用格式：

if (condition)
{
    statements;
}
else if (condition)
{
    statements;
}
else
{
    statements;
}

for、foreach语句

for 语句使用格式：

for (initialization; condition; update)
{
    statements;
}

空的 for 语句（所有的操作都在initialization、condition 或 update中实现）使用格式

for (initialization; condition; update);    // update user id

foreach 语句使用格式

foreach (object obj in array)
{
    statements;
}

注意：

1．在循环过程中不要修改循环计数器。

2．对每个空循环体给出确认性注释。

while语句

while 语句使用格式：

while (condition)
{
    statements;
}

空的 while 语句使用格式：

while (condition)
    ;

do – while 语句

do – while 语句使用格式：

do
{
    statements;
} while (condition);

switch – case语句

switch – case 语句使用格式：

switch (condition)
{
    case 1:
        statements;
        break; 

    case 2:
        statements;
        break;
 
    default:
        statements;
        break;
}

注意：

1．语句switch中的每个case各占一行。

2．语句switch中的case按字母顺序排列。

3．为所有switch语句提供default分支。

4．所有的非空 case 语句必须用 break; 语句结束。

try – catch语句

try – catch 语句使用格式：

try
{
    statements;
}
catch (ExceptionClass e)
{
    statements;
}
finally
{
    statements;
}

using块语句

using 块语句使用格式：

using (object) 
{ 
    statements; 
}

文档下载地址：

[ypbtn]http://pan.baidu.com/s/1i4Tm8DJ[/ypbtn]

【心得】我的C#开发规范最先出现在初晴神社。

规范 归档 - 初晴神社