CSharp代码编写指导规范

项目： 规范 文号： COD-STA-01 版本： V1.0 编写人： Antony 时间： 2005-11-4

C#代码编写指导规范

版本变更记录： 时间 版本 作者/修改人 修改原因 2005-11-4

V1.0 Antony 正式发布

深圳市金谷科技有限公司 C#代码编写指导规范

目 录

1 简介 ................................................................................ 3

1.1 目标 .......................................................................... 3 1.2 范围 .......................................................................... 3 1.3 基本依据 ...................................................................... 3 1.4 标记约定 ...................................................................... 3 1.5 术语和缩略语 .................................................................. 3 1.6 参考 .......................................................................... 3 2 通用规则 ............................................................................ 3 3 命名约定 ............................................................................ 3

3.1 一般规则 ...................................................................... 3 3.2 命名空间命名 .................................................................. 4 3.3 类及结构命名 .................................................................. 4 3.4 接口命名 ...................................................................... 5 3.5 枚举命名 ...................................................................... 5 3.6 事件命名 ...................................................................... 5 3.7 控件命名 ...................................................................... 5 4 注释和内嵌文档 ....................................................................... 6

4.1 文件头部 ...................................................................... 6 4.2 使用#region 标注一组相关的非公共成员 .......................................... 7 4.3 类的注释 ...................................................................... 7 4.4 类属性注释规范 ................................................................ 7 4.5 方法注释规范 .................................................................. 7 4.6 代码间注释规范 ................................................................ 8 5 声明 ................................................................................ 8

5.1 每行的声明数 .................................................................. 8 5.2 初始化 ........................................................................ 8 5.3 类和接口的声明 ................................................................ 8 6 表达式 .............................................................................. 9

6.1 简单表达式 .................................................................... 9 6.2 return语句 .................................................................... 9 6.3 if, if-else, if else-if else 语句 ............................................. 9 6.4 for, foreach 语句 ............................................................ 10 6.5 while, do-while语句 .......................................................... 10 6.6 switch 语句 .................................................................. 11 6.7 try-catch 语句 ............................................................... 11 7 留白 ............................................................................... 11

7.1 空行 ......................................................................... 11 7.2 空格 ......................................................................... 12 8 编码准则 ........................................................................... 12

8.1 可见性 ....................................................................... 12 8.2 Magic Number ................................................................. 12 8.3 异常处理 ..................................................................... 12 8.4 其他 ......................................................................... 12 9 代码示例 ........................................................................... 13

9.1 括号的位置示例 ............................................................... 13

第 1 页 共 15 页

深圳市金谷科技有限公司 C#代码编写指导规范

9.2 变量命名示例 ................................................................. 13 10 编码风格 .......................................................................... 14

第 2 页 共 15 页

深圳市金谷科技有限公司 C#代码编写指导规范

1 简介

1.1 目标

本主题提供C#编程语言的命名指南。希望能对下述情况有积极的作用： ➢ 避免 Errors/Bugs ，特别是难以查询的Errors/Bugs。 ➢ 规范不良的编码习惯。 ➢ 提高程序的可维护性。

1.2 范围

规范只针对 C#编程语言。

1.3 基本依据

本文档主要依据 MSDN中命名指南之.NET Framework 常规参考。

1.4 标记约定

（1）规则表明没有特别的理由必须要遵守的要求。违反规则的编码人员必须至少同有经验的同事商量并取得违反规则的理由共识后才能实施。必须对违反规则的代码进行注解。

(2)Recommendations建议:正常情况下优先考虑，如果有违反建议的编码，应该同有经验的同事商量并取得违反建议的理由共识后才能实施，推荐对违反建议的代码进行注解。

1.5 术语和缩略语 1.6 参考

MSDN-命名指南

Coding Standard: C# - philips

2 通用规则

（1）每一次不能执行建议的编码规则，必须要有合理的理由，理由不包括个人的编码风格因素。 （2）在一个文件中不要混合不同所有者的代码，因为第三方的代码可能不会遵守相同的编码规范。

3 命名约定

3.1 一般规则

（1）使用 US-English 作为命名标识符依据。

（2）使用命名标识符的 Pascal 大小写、Camel 大小写。

（3）常见类型的标记法： IDENTIFIER Class Enum type Enum values Event Exception class Field Const Field Read-only Static Field Interface Method Namespace Parameter Property CASE Pascal Pascal Pascal Pascal Pascal camel camel camel Pascal Pascal Pascal camel Pascal 第 3 页 共 15 页

EXAMPLE AppDomain ErrorLevel FatalError ValueChange WebException listItem maximumItems redValue IDisposable ToString System.Drawing typeName BackColor

深圳市金谷科技有限公司 C#代码编写指导规范

DENTIFIER CASE EXAMPLE

（4）在标识符名称中不再使用Hungarian 符号法以及其他附加类型表示法。 （5）不要给成员变量名称加匈牙利语类型表示法的前缀。 （6）不要创建具有仅是大小写有区别的标识符名称。

在下面的示例中，calculate 和 Calculate 是不适当的方法名称，原因是它们仅在大小写方面有区别。 void calculate() void Calculate()

（7）不要将缩写或缩略形式用作标识符名称的组成部分。

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

（8）不要在标识符名称中使用下划线。

（9）使用描述标识符含义的名称，而不要使用描述标识符类型的名称。

开发工具将提供有关参数的类型的有意义的信息。因此，通过描述意义，可以更好地使用参数的名称。少用基于类型的参数名称，仅在适合使用它们的地方使用它们。 以下是正确命名的参数的示例。 Type GetType(string typeName) string Format(string format, object[] args)

（10）不要给标识符名称增加代码文档相关的前缀。

（11） 使用包含装配件的命名空间加上标识符名称命名装配件。

如一组类在NameSpace: Philips.PmsMR.Platform.OSInterface.下,由这些类产生的assembly应该被命名为 Philips.PmsMR.Platform.OSInterface.dll.。 （12）使用 Pascal 标记法命名源文件。

（13）仅在类构造器中使用 “this.”关键字 。

（14）不要同时使用容易同数字引起混淆的字符。如O, o, l和 0，1。

3.2 命名空间命名

（1）应当对命名空间使用 Pascal 大小写，并用句点分隔逻辑组件。

建议的写法： ...。

（2）不要为命名空间和类使用相同的名称。

例如，不要既提供 Debug 命名空间也提供 Debug 类。

3.3 类及结构命名

（1）不要为class 或 struct 填加后缀。 （2）使用名词或名词短语命名类及struct。

（3）应该总是将后缀 Attribute 添加到自定义属性类。

以下是正确命名的属性类的示例。 如：public class ObsoleteAttribute{} （4）在适当的地方，使用复合单词命名派生的类。派生类名称的第二个部分应当是基类的名称。

例如，ApplicationException 对于从名为 Exception 的类派生的类是适当的名称，原因是 ApplicationException 是一种 Exception。请在应用该规则时进行合理的判断。例如，Button 对于从 Control 派生的类是适当的名称。尽管按钮是一种控件，但是将 Control 作为类名称的一部分将使名称不 第 4 页 共 15 页

深圳市金谷科技有限公司 C#代码编写指导规范

必要地加长。

3.4 接口命名

（1）给接口名称加上字母 I 前缀，以指示该类型为接口。

（2）在定义类/接口对（其中类是接口的标准实现）时使用相似的名称。两个名称的区别应该只是接口名称上有字母 I 前缀。

以下代码示例阐释如何定义 IComponent 接口及其标准实现 Component 类。 public interface IComponent { // Implementation code goes here. } public class Component: IComponent { // Implementation code goes here. }

3.5 枚举命名

➢ ➢ ➢ ➢ ➢

枚举 (Enum) 值类型从 Enum 类继承。以下规则概述枚举的命名指南： 对于 Enum 类型和值名称使用 Pascal 大小写。 少用缩写。

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

对大多数 Enum 类型使用单数名称，但是对作为位域的 Enum 类型使用复数名称。 总是将 FlagsAttribute 添加到位域 Enum 类型。

3.6 事件命名

(1)对事件处理程序名称使用 EventHandler 后缀。

public delegate void MouseEventHandler(object sender, MouseEventArgs e); （2）考虑用动词命名事件。例如，命名正确的事件名称包括 Clicked、Painting 和 DroppedDown。 （3）不要使用event或其他的类型标识作为 事件名的后缀。

（4）使用动名词（动词的“ing”形式）创建表示事件前的概念的事件名称，用过去式(-ed)表示事件后。

例如，可以取消的 Close 事件应当具有 Closing 事件和 Closed 事件。不要使用 BeforeXxx/AfterXxx 命名模式。 （5）对 event handler使用 前缀On。

如事件Closing 的 event handler 应该命名为 OnClosing()。

3.7 控件命名

（1）在Visual Studio .NET开发环境中使用Form Designer添加控件时，会为控件自动命名。如果某个控件只用于显示信息，没有任何事件和状态变化的操作，则无需修改缺省的命名。

（2）以下为常用控件前缀： 控件类型 前缀 Form form Label lbl LinkLable llb Button btn TextBox tbx 第 5 页 共 15 页

深圳市金谷科技有限公司 C#代码编写指导规范 mmu MainMenu CheckBox cbx rbn RadioButton GroupBox gbx PictureBox pbx Panel pnl DataGrid dgd ListBox lbx CheckedListBox clb ComboBox cbb ListView lvw TreeView tvw TabControl tcl DateTimePicker dtp MonthCalendar mcr HScrollBar hsb VScrollBar vsb Timer tmr Splitter slr DomainUpDown dud NumericUpDown nud TrackBar tkr ProgressBar pbr RichTextBox rtb ImageList ilt HelpProvider hpr ToolTip ttp ContextMenu cmu Toolbar tbr StatusBar sbr NotifyIcon nin OpenFileDialog ofdlg SaveFileDialog sfdlg FolderBrowserDialog fbdlg FontDialog ftdlg ColorDialog crdlg PrintDialog ptdlg PrintPriviewDialog ppdlg PrintPriviewControl ppctl ErrorProvider epr PrintDocument pdt PageSetupDialog psdlg CrystalReportViewer crv （3）未在以上列表的控件，可以自定义前缀，或者使用全名作为前缀。 4 注释和内嵌文档

4.1 文件头部

每一个文件的头部要添加：

#region Copyright spsp., 2003 // 第 6 页 共 15 页

深圳市金谷科技有限公司 C#代码编写指导规范

// All rights are reserved. Reproduction or transmission in whole or in part, in // any form or by any means, electronic, mechanical or otherwise, is prohibited // without the prior written consent of the copyright owner. // // Filename: PatientAdministration.cs // #endregion 4.2 使用#region 标注一组相关的非公共成员 4.3 类的注释

///

如果模块有修改，则每次修改必须添加以下注释：

///

4.4 类属性注释规范

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

///

4.5 方法注释规范

在类的方法声明前必须以以下格式编写注释

///

/// \"><参数说明> ///

///<对方法返回值的说明，该说明必须明确说明返回的值代表什么含义> ///

第 7 页 共 15 页

深圳市金谷科技有限公司 C#代码编写指导规范

4.6 代码间注释规范

代码间注释分为单行注释和多行注释：

单行注释：

//<单行注释>

多行注释： /*多行注释1 多行注释2 多行注释3*/

5 声明

5.1 每行的声明数

每个声明单独占用一行，而不要将多个声明放入一行。 例如，这样声明：

int level; int size;

而不是：

int level, size;

5.2 初始化

尽量在声明变量的同时初始化。 例如：

string name = myObject.Name;

当初始化对话框时，请使用using语句。

例如：

using (OpenFileDialog openFileDialog = new OpenFileDialog()) { … }

5.3 类和接口的声明

当声明类（class）和接口（interface）时，请遵守以下准则： ➢ 在函数名和参数列的左括号“(”之间不要添加空格（Space）。 ➢ 左花括号应新起一行。

➢ 右花括号应新起一行，并与对应左花括号的缩进一致。 例如：

class MySample : MyClass, IMyInterface {

int myInt; public MySample(int myInt) { this.myInt = myInt ; } void Inc() { ++myInt; } void EmptyMethod() {

第 8 页 共 15 页

深圳市金谷科技有限公司 C#代码编写指导规范

}

}

6 表达式

6.1 简单表达式

每行仅包含一个简单表达式。

6.2 return语句

return语句可以添加最外层的括号，也可以不添加，不做强制要求。 例如：

return (n * (n + 1) / 2); return n * (n + 1) / 2; 均可。

6.3 if, if-else, if else-if else 语句

依如下风格，使用if, if else, if else-if else语句：

if (condition) { DoSomething(); … }

if (condition) { DoSomething(); … } else { DoSomethingOther(); … }

if (condition) { DoSomething(); … }

else if (condition) { DoSomethingOther(); … } else { DoSomethingOtherAgain(); … }

当一个分支只包含一个语句时，推荐省略该分支的花括号，但仍将分支语句与条件语句放入两行。 例如，推荐：

if (condition)

第 9 页 共 15 页

深圳市金谷科技有限公司 C#代码编写指导规范

DoSomething();

而不是：

if (condition) { DoSomething(); }

if (condition) DoSomething();

6.4 for, foreach 语句

依如下风格，使用for, foreach语句：

for (int i = 0; i < 5; ++i) { … }

foreach (int i in IntList) { … }

当一个循环只包含一个语句时，推荐省略该循环的花括号。 例如，推荐：

foreach (int i in IntList) DoSomething();

foreach (int i in IntList);

而不是：

foreach (int i in IntList) {

DoSomething(); }

foreach (int i in IntList){}

6.5 while, do-while语句

依如下风格，使用while, do while语句：

while (condition) { … } do { ...

} while (condition);

当一个循环只包含一个语句时，推荐省略该循环的花括号。 例如，推荐：

while (condition) DoSomething(); while (condition);

而不是：

while (condition) { DoSomething();

第 10 页 共 15 页

深圳市金谷科技有限公司 C#代码编写指导规范

}

while (condition){}

6.6 switch 语句

依如下风格，使用switch语句：

switch (condition) { case A: ... break; case B: ... break; default: ... break; }

6.7 try-catch 语句

依如下风格，使用switch语句：

try { … }

catch (Exception) {} try { … }

catch (Exception e) { ... } try { … }

catch (Exception e) { … }

finally { … }

7 留白

7.1 空行

当属于以下情况时，使用一个空行将上下两部分代码分开：

➢ 类（class）以及接口（interface）声明之间（尽量将每个类分别放入不同的源代码文件，以避免这种

情况）

第 11 页 共 15 页

深圳市金谷科技有限公司 C#代码编写指导规范 ➢ ➢ ➢ ➢ ➢

类以及接口声明中的逻辑段落之间 函数之间（method） 属性之间（property）

一个函数中局部变量和函数的第一个表达式之间 函数中的逻辑段落之间

7.2 空格

逗号和分号后应加入一个空格（Space）。 例如：

TestMethod(a, b, c); 而不是：

TestMethod(a,b,c);

TestMethod( a, b, c );

除非特例（参见特例情况），算术、逻辑运算符两端应各加入一个空格（Space）。 例如：

a = b; i < 10

而不是：

a=b; i<10;

特例情况：

增量运算符两端不加入空格。例如：++i 加入空格后逻辑上不合理的情况

8 编码准则

8.1 可见性

（1）除非特例（参见特例情况），将类所有成员变量的可见性定义为私有。 （2）使用公有或者保护的properties访问类的成员变量。

（3）推荐不显式写出“private”关键字，C#中默认的可见性为私有。 （4）特例情况：静态值域(static fields)的可见性可以定义为公有。

8.2 Magic Number

（1）不要使用魔数(magic number)。 （2）使用常量代替之。 例如：

public class MyMath { public const double PI = 3.14159; }

8.3 异常处理

（1）捕捉特定的异常，而不要捕捉一般的异常。 （2）不要捕捉而不处理异常。

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

（4）如果必要，可以编写自己的异常类。

（5）自定义异常应实现IApplicationException，而不是派生SystemException。

8.4 其他

（1）在代码中应该使用相对路径，而不是使用具体的路径和驱动器名。

第 12 页 共 15 页

深圳市金谷科技有限公司 C#代码编写指导规范 （2）错误消息应该帮助并指导用户解决问题，使用“登陆数据库失败。请确保登陆id和密码正确”之类的错误消息，而不是“应用程序出错”之类的错误消息。

9 代码示例

9.1 括号的位置示例

namespace ShowMeTheBracket { public enum Test { TestMe, TestYou } public class TestMeClass { Test test; public Test Test { get { return test; } set { test = value; } } void DoSomething() { if (test == Test.TestMe) { //...stuff gets done } else { //...other stuff gets done } } } }

9.2 变量命名示例

for (int primeCandidate = 1; primeCandidate < num; ++primeCandidate) isPrime[primeCandidate] = true;

for (int factor = 2; factor < num / 2; ++factor) { int factorableNumber = factor + factor; while (factorableNumber <= num) { isPrime[factorableNumber] = false; factorableNumber += factor; } }

for (int primeCandidate = 0; primeCandidate < num; ++primeCandidate)

第 13 页 共 15 页

深圳市金谷科技有限公司 C#代码编写指导规范

{ }

if (isPrime[primeCandidate]) Console.WriteLine(primeCandidate + \" is prime.\");

10 编码风格

（1）不要在一组相关的类或在一个模块中混合使用不同的编码风格。

（2）一个类或结构中的public,protected,private声明应保持一定的顺序。 （3）使用tabs而不是空格。

（4）在源文件中，每一行不要超过80个字符。

第 14 页 共 15 页