C# 编程规范_c#机器人编程架构规范

 

本规范包括两个个部分：“命名规范”、“代码格式”。

编写此规范的目的是，为大家编写清晰、易读的代码提供良好的建议。也为公司的代码审阅提供一个可供参考的标准。

       C# 编码规范的主要内容来自于 MSDN 中《 Design Guidelines for Class Library Developers 》，其次是摩托罗拉（中国）电子有限公司陈世忠编著的《 C++ 编码规范》。另外，也参考了作者主持反编译的 ASP .net 源码、 Microsoft 公开源码的 .NET 平台实现 Rotor 的系统类库、 ErichGamma 等的《设计模式——可复用面向对象软件的基础》、 Bjarne Stroustrup 的《 The C++ Programming Language 》、以及作者在使用 C# 进行编码工作过程中积累的一些工作经验。

.NET Framework SDK 提供了三种大写样式提供参考。分别：

Ø   Pascal 大小写

Ø   Camel 大小写

Ø   大写

大小写

将标识符的首字母和后面连接的每个单词的首字母都大写。可以对三字符或更多字符的标识符使用 Pascal 大小写。

例如：

BackColor

大小写

标识符的首字母小写，而每个后面连接的单词的首字母都大写。

例如：

backColor

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

例如：

System.IO

System.Web.UI

可能还必须大写标识符以维持与现有非托管符号方案的兼容性，在该方案中所有大写字母经常用于枚举和常数值。一般情况下，在使用它们的程序集之外这些字符应当是不可见的。

大小写规则使用参考表

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

1 、不要使用要求区分大小写的名称。

对于区分大小写和不区分大小写的语言，组件都必须完全可以使用。不区分大小写的语言无法区分同一上下文中仅大小写不同的两个名称。因此，在创建的组件或类中必须避免这种情况。

2 、不要创建仅是名称大小写有区别的两个命名空间。

例如，不区分大小写的语言无法区分以下两个命名空间声明。

namespace ee.cummings;

namespace Ee.Cummings;

3 、不要创建具有仅是大小写有区别的参数名称的函数。

下面的示例是不正确的。

void MyFunction(string a, string A)

4 、不要创建具有仅是大小写有区别的类型名称的命名空间。

在下面的示例中， Point p 和 POINT p 是不适当的类型名称，原因是它们仅是大小写有区别。

System.Windows.Forms.Point p

System.Windows.Forms.POINT p

5 、不要创建具有仅是大小写有区别的属性名称的类型。

在下面的示例中， int Color 和 int COLOR 是不适当的属性名称，原因是它们仅是大小写有区别。

int Color {get, set}

int COLOR {get, set}

6 、不要创建具有仅是大小写有区别的方法名称的类型。

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

void calculate()

void Calculate()

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

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

例如，使用 GetWindow ，而不要使用 GetWin 。

2 、不要使用计算机领域中未被普遍接受的缩写。

3 、在适当的时候，使用众所周知的缩写替换冗长的词组名称。

例如，用 UI 作为 User Interface 的缩写，用 OLAP 作为 On-line Analytical Processing 的缩写。

4 、在使用缩写时，对于超过两个字符长度的缩写请使用 Pascal 大小写。

例如，使用 HtmlButton 或 HTMLButton 。但是，应当大写仅有两个字符的缩写，如， System.IO ，而不是 System.Io 。

避免使用与常用的 .NET 框架命名空间重复的类名称。例如，不要将以下任何名称用作类名称： System 、 Collections 、 Forms 或 UI 。有关 .NET 框架命名空间的列表，请参阅类库。

另外，避免使用和以下关键字冲突的标识符。

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

CompanyName.TechnologyName[.Feature][.Design]

例如：

Microsoft.Media

Microsoft.Media.Design

给命名空间名称加上公司名称或者其他知名商标的前缀可以避免两个已经发布的命名空间名称相同的可能性。例如， Microsoft.Office 是由 Microsoft 提供的 Office Automation Classes 的一个适当的前缀。

在第二级分层名称上使用稳定的、公认的技术名称。将组织层次架构用作命名空间层次架构的基础。命名一个命名空间，该命名空间包含为具有 .Design 后缀的基命名空间提供设计时功能的类型。例如， System.Windows.Forms.Design 命名空间包含用于设计基于 System.Windows.Forms 的应用程序的设计器和相关的类。

嵌套的命名空间应当在包含它的命名空间中的类型上有依赖项。例如， System.Web.UI.Design 中的类依赖于 System.Web.UI 中的类。但是， System.Web.UI 中的类不依赖于 System.UI.Design 中的类。

应当对命名空间使用 Pascal 大小写，并用句点分隔逻辑组件，如 Microsoft.Office.PowerPoint 中所示。如果您的商标使用非传统的大小写，请遵循您的商标所定义的大小写，即使它与规定的 Pascal 大小写相背离。例如，命名空间 NeXT.WebObjects 和 ee.cummings 阐释了对于 Pascal 大小写规则的适当背离。

如果在语义上适当，使用复数命名空间名称。例如，使用 System.Collections 而不是 System.Collection 。此规则的例外是商标名称和缩写。例如，使用 System.IO 而不是 System.IOs 。

不要为命名空间和类使用相同的名称。例如，不要既提供 Debug 命名空间也提供 Debug 类。

最后，请注意命名空间名称不必非得与程序集名称相似。例如，如果命名程序集 MyCompany.MyTechnology.dll ，它没有必要非得包含 MyCompany.MyTechnology 命名空间。

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

1 、使用名词或名词短语命名类。

2 、使用 Pascal 大小写。

3 、少用缩写。

4 、不要使用类型前缀。

如在类名称上对类使用 C 前缀。例如，使用类名称 FileStream ，而不是 CFileStream 。

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

6 、有时候需要提供以字母 I 开始的类名称，虽然该类不是接口。

只要 I 是作为类名称组成部分的整个单词的第一个字母，这便是适当的。例如，类名称 IdentityStore 是适当的。

7 、在适当的地方，使用复合单词命名派生的类。

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

下面是正确命名的类的示例。

public class FileStream

public class Button

public class String

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

1 、用名词或名词短语，或者描述行为的形容词命名接口。

例如，接口名称 IComponent 使用描述性名词。接口名称 ICustomAttributeProvider 使用名词短语。名称 IPersistable 使用形容词。

2 、使用 Pascal 大小写。

3 、少用缩写。

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

5 、在定义类 / 接口对（其中类是接口的标准实现）时使用相似的名称。

两个名称的区别应该只是接口名称上有字母 I 前缀。

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

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

public interface IServiceProvider

public interface IFormatable

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

public interface IComponent

{

// Implementation code goes here.

}

public class Component: IComponent

{

// Implementation code goes here.

}

应该总是将后缀 Attribute 添加到自定义 Attribute 类。以下是正确命名的 Attribute 类的示例。

public class ObsoleteAttribute

{

}

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

1 、对于 Enum 类型和值名称使用 Pascal 大小写。

2 、少用缩写。

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

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

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

Field 应该以 _ 开头。 _ 表示 Member 。

例如

private OleDbConnection _connection = null ;

非静态 field 也可以以下命名方式，例如：

private string _id;[1]

在微软公布的共享版的 C# 代码中，采用的“ _ ”前缀的风格，在《设计模式》一书中的所有源码也是使用“ _ ”风格。

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

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

2 、使用 Pascal 大小写。

4 、对静态 field 名称使用匈牙利语表示法前缀。

5 、建议尽可能使用静态属性而不是公共静态 field 。

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

1 、使用描述性参数名称。

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

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

3 、使用描述参数的含义的名称，而不要使用描述参数的类型的名称。

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

4 、不要使用保留的参数。

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

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

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

Type GetType(string typeName)

string Format(string format, object[] args)

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

使用动词或动词短语命名方法。

使用 Pascal 大小写。

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

RemoveAll()

GetCharArray()

Invoke()

在 Java 语言流行的编码风格中，行使用 camel 大小写命名方法，在《 C++ 编码规范》（陈世忠编著人民邮电出版社），也是建议使用 camel 大小写。本规范中采用的是 MSDN 中建议的 C# 命名规则，和系统类库的命名规则一致。

以下规则概述属性的命名指南：

1 、使用名词或名词短语命名属性。

2 、使用 Pascal 大小写。

3 、不要使用匈牙利语表示法。

4 、考虑用与属性的基础类型相同的名称创建属性。

例如，如果声明名为 Color 的属性，则属性的类型同样应该是 Color 。请参阅本主题中后面的示例。

以下代码示例阐释正确的属性命名。

public class SampleClass

{

public Color BackColor

{

// Code for Get and Set accessors goes here.

}

}

以下代码示例阐释提供其名称与类型相同的属性。

public enum Color

{

// Insert code for Enum here.

}

public class Control

{

public Color Color

{

get

{

// Insert code here.

}

set

{

// Insert code here.

}

}

}

以下代码示例不正确，原因是 Color 属性是 Integer 类型的。

public enum Color

{

// Insert code for Enum here.

}

public class Control

{

public int Color

{

get

{

// Insert code here.

}

set

{

// Insert code here.

}

}

}

在不正确的示例中，不可能引用 Color 枚举的成员。 Color.Xxx 将被解释为访问一个成员，该成员首先获取 Color 属性（在 Visual Basic 中为 Integer 类型，在 C# 中为 int 类型）的值，然后再访问该值的某个成员（该成员必须是 System.Int32 的实例成员）。

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

1 、对 event 处理程序名称使用 EventHandler 后缀。

2 、定两个名为 sender 和 e 的参数。

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

3 、 EventArgs 后缀命名 event 参数类。

5 、要在类型的 event 声明上使用前缀或者后缀。

例如，使用 Close ，而不要使用 OnClose 。

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

( 补充例子 )

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

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

以下示例阐释正确命名的 event 参数类。

public class MouseEventArgs : EventArgs

{

int x;

int y;

public MouseEventArgs( int x, int y)

{

this .x = x;

this .y = y;

}

public int X

{

get

{

return x;

}

}

public int Y

{

get

{

return y;

}

}

}

控件的命名，以前缀作为标识某种类型的控件。具体如下：

局部变量的命名，不建议采用所有的变量在函数头声明，声明变量的原则是，以逻辑单元划分，在离使用的地方最近的位置声明变量通常能够使代码变得更清晰。

局部变量的命名建议采用 Camel 大小写。例如

DataTable dataTable;

对于 for 循环的变量名，继续使用 i 、 j 、 k 。

for ( int i=0; i<10; i++)

{

for ( int j=0; j<20; j++)

{

}

}

2.18 集合和数组变量的命名

集合变量的命名使用 List 作为后缀，数组变量的命名使用 Array 后缀，比使用复数形式更清晰。例如：

WfActivityCollection activityList = // get collection

foreach (WfActivity activity in activityList)

{

}

WfActivity[] activityArray = // get array

       在系统中，有一些经常出现的，用途一致的，建议采用统一的变量命名风格。以下是参考，但不做硬性要求。

命名参考

通常来说， WebUI 层的代码会占整个工程的代码的 60% 以上。所以说， WebUI 层的编码规范尤其重要。

在页面中声明全局变量 theForm ，在 window_onload 时初始化，然后使用。

例如：

在页面 PersonInfo.aspx 文件中， Form 的名字是 PersonInfo ，在某函数中需要访问其中的文本框 txtName 的值时，代码应该这样写：

< Script language ="javascript">

<!--

var theForm; // 声明theForm 变量，在window_onload事件中初始化。

function window_onload()

{

theForm = PersonInfo;

}

function toolbar_onclick(evt)

{

              // 这样做，比直接使用PersonInfo.txtName 清晰多了

theForm.txtName.value = “ xxxxxxxxxxxxx ” ;

}

//-->

</ Script >

如果页面需要一些初始化操作，响应的函数，建议统一使用 window_onload 的命名，例如：

    < head >

< Script language ="javascript">

<!--

function window_onload()

{

              // do something

}

//-->

</ Script >

       </ head >

< body onload ="window_onload();">

使用 ShowDialogBox 弹出的页面，通常需要有返回值处理，同时需要对 Esc 键响应关闭窗口。对此类代码的写法规范如下：

< SCRIPT language ="javascript">

<!--

var pageReturnValue;

function window_onbeforeunload()

{

window.returnValue = pageReturnValue;

}

function document_onkeydown()

{

if ( event .keyCode == 27)

{

window.close();

}

}

//-->

</ SCRIPT >

< SCRIPT LANGUAGE ="javascript" FOR ="document" EVENT ="onkeydown">

<!--

document_onkeydown()

//-->

</ SCRIPT >

</ head >

< body onload ="window_onload();" onbeforeunload ="return window_onbeforeunload()">

对 toolbar 的 Click 事件的响应函数名称统一规定为 toolbar_onclick(evt) 。例如：

function toolbar_onclik(evt)

{

switch (evt.ID)

{

case "Add":

f_addProcessDef( true );

break ;

case "Remove":

f_removeProcessDef( true );

break ;

default :

break ;

}

}

普通的函数考虑使用 f_ 前缀。使用 f_ 前缀的原因是在微软提供的一些 HTC 中，使用了这一风格，当把函数指针作为参数传递时，使用 f_ 作为前缀，代码显得比较清晰。但是对于特定的函数，不是用此命名方法。例如： window_onload 等。

例如：

function f_add()

{

var cellArray = oRow.cells;

var oRow = oTable.rows[0];

}

function window_onload()

{

}

function document_onkeydown()

{

}

function window_onbeforeunload()

{

}

变量的命名，如果是数组，考虑使用 Array 作为后缀，例如：

var cellArray = oRow.cells;

var itemArray = new Array();

如果变量是对象，考虑使用 o 作为前缀。例如：

var oRow = oTable.rows[0];

JavaScript 中，循环所的写法如下，不使用 for … in 的语法：

var arrayLength = itemArray.length;           

for ( var i=0; i<arrayLength; i++)

{

for ( var j=0; j<100; j++)

{

//do someting ...

}

}

在需要弹出对话框的页面的头部添加如下语句：

var dialogBoxUrl = "../DialogBox.aspx";

在需要弹出对话框时，如下处理：

function f_search(callByMenu)

{

var dialogBoxFeature = "dialogWidth:400px; dialogHeight:250px; resizable:yes;";

var pageTitle = "查找任务";

var pageUrl = "WfAdmin/AssignmentSearchInfoInput.aspx";

var rtnValue = showDialogBox(dialogBoxUrl, pageUrl, pageTitle, dialogBoxFeature);

}

       每个文件头部都应该有注释，用来描述作者、最后修改时间、相关描述、修改记录等。

/*

     作        者： xxxx xxx xxx

     最后修改时间： xxxx 年x月xx日

描        述： xxxxxxxxxxxxxxxxxxxxxxxx

     更新纪录：

1、  xxxx 年x 月xx日，修改人xxx，增加功能包括：xxxxx

*

       在所有为 Public 修饰符的方法都要添加注释。注释包括 Summary 和 Remark 两部分， Summary 部份是必需的， Remark 部份可选。方法的注释，还应该包含参数的注释，返回值的注释。如果你确定你抛出的异常列表，就把所抛出异常的注释加上。

例如：

/// <summary>

/// 简要注释文本

/// </summary>

/// <remarks>

/// 详细注释文本

/// </remarks>

public void F()

{

}

4.2.1      

public void F1()

{

// ...

}

public void F2()

{

// ...

}

       原因

       就像文章要分段一样。这样便于阅读。

例子

public void F1()

{

if (condition)

{

//...

}

return this ; // 返回语句之前加一空行

}

例外：

除非该函数过于简单，比如只有一两条语句。

       使用花括号进行段落划分能够指定方法内的变量的生命区域，从而使得代码更少出现一些因为不小心或者拼写错误导致的 Bug 。例如：

public void F()

{

// 段落 1

{

int i;

}

// 段落 2

{

int j, k;

}

}

要独占一行

       关于花括号的放置方法有很多风格，争论也有很长时间了。但我们坚持认为，单独放置更明显一点，查找和配对也更直接。

       另外一种流行的风格是将左花括号和前面的语句放在一行，这样代码更紧凑，尤其是当花括号中的语句不多时更明显。这种风格源于杂志和书籍在排版时的美观要求，作为编程者，我们看问题的角度与排版不尽一致。

                     if(saaa)

                     {

                     }

                // 这种方式表达空循环不够清楚

for ( int i=0; i<TIMEOUT; i++);

// 即使是空循环，也保留{} ，这样就清楚多了。

for ( int i=0; i<TIMEOUT; i++)

{

}

例子：

// 两条语句放在一行

if (buffer.Empty) status = ERROR_EMPTY;

// 这样要清晰一些

if (buffer.Empty)

{

status = ERROR_EMPTY;

}

原因：

       简化一行，清晰好读。

       便于统计工具计算代码行数。

       合并多条语句于一行没有明显的好处。

       某些语句过长，不易于阅读，可以采用分行的办法。

语句的分行

在程序中嵌入 Sql 语句时，使用 Sql 分行使得代码更容易阅读。例如

strSql = @"

SELECT Name, PwdHash, [Builtin], Description

FROM Hrms_Users

Where Id = ?

";

判断表达式的分行

if 判断表达式多于一个的时候，采用分行编写，容易阅读。并且方便编写注释。

例如：

if ((dt != null ) // 不为空值

&& (dt.Rows.Count != 0) // 并且数量不为0

)

{

//do something.....

}

在调用参数较为复杂的方法时，采用分行编写，容易阅读。并且方便编写注释。

例如：

db.RunSelectCommand(

sql,

DbUtils.MakeGuidInParam("@Id", entryID),

out dt

);

当一个方法的参数过多时，建议采用分行的写法。例如：

public void RunSelectCommand(

string commandString,

out DataTable dataTable,

int pageIndex,

int pageSize

)

{

}