CSharp代码编写指导规范.doc

项目：规范文号：COD-STA-01版本：V1.0编写人：Antony时间：2005-11-4 C#代码编写指导规范版本变更记录：时间版本作者/修改人修改原因2005-11-4V1.0Antony正式发布目 录1 简介31.1 目标31.2 范围31.3 基本依据31.4 标记约定31.5 术语和缩略语31.6 参考32 通用规则33 命名约定33.1 一般规则33.2 命名空间命名43.3 类及结构命名43.4 接口命名53.5 枚举命名53.6 事件命名53.7 控件命名54 注释和内嵌文档64.1 文件头部64.2 使用#region 标注一组相关的非公共成员74.3 类的注释74.4 类属性注释规范74.5 方法注释规范74.6 代码间注释规范75 声明85.1 每行的声明数85.2 初始化85.3 类和接口的声明86 表达式96.1 简单表达式96.2 return语句96.3 if, if-else, if else-if else 语句96.4 for, foreach 语句106.5 while, do-while语句106.6 switch 语句116.7 try-catch 语句117 留白117.1 空行117.2 空格128 编码准则128.1 可见性128.2 Magic Number128.3 异常处理128.4 其他129 代码示例139.1 括号的位置示例139.2 变量命名示例1310 编码风格141 简介1.1 目标本主题提供C#编程语言的命名指南。希望能对下述情况有积极的作用： 避免 Errors/Bugs ，特别是难以查询的Errors/Bugs。 规范不良的编码习惯。 提高程序的可维护性。1.2 范围规范只针对 C#编程语言。1.3 基本依据本文档主要依据 MSDN中命名指南之.NETFramework常规参考。1.4 标记约定（1）规则表明没有特别的理由必须要遵守的要求。违反规则的编码人员必须至少同有经验的同事商量并取得违反规则的理由共识后才能实施。必须对违反规则的代码进行注解。(2)Recommendations建议:正常情况下优先考虑，如果有违反建议的编码，应该同有经验的同事商量并取得违反建议的理由共识后才能实施，推荐对违反建议的代码进行注解。1.5 术语和缩略语1.6 参考MSDN-命名指南Coding Standard: C# - philips2 通用规则（1）每一次不能执行建议的编码规则，必须要有合理的理由，理由不包括个人的编码风格因素。（2）在一个文件中不要混合不同所有者的代码，因为第三方的代码可能不会遵守相同的编码规范。3 命名约定3.1 一般规则（1）使用 US-English 作为命名标识符依据。（2）使用命名标识符的 Pascal 大小写、Camel 大小写。（3）常见类型的标记法：IDENTIFIERCASEEXAMPLEClassPascalAppDomainEnum typePascalErrorLevelEnum valuesPascalFatalErrorEventPascalValueChangeException classPascalWebExceptionFieldcamellistItemConst FieldcamelmaximumItemsRead-only Static FieldcamelredValueInterfacePascalIDisposableMethodPascalToStringNamespacePascalSystem.DrawingParametercameltypeNamePropertyPascalBackColorDENTIFIER 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 作为类名称的一部分将使名称不必要地加长。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）以下为常用控件前缀：控件类型前缀FormformLabellblLinkLablellbButtonbtnTextBoxtbxMainMenummuCheckBoxcbxRadioButtonrbnGroupBoxgbxPictureBoxpbxPanelpnlDataGriddgdListBoxlbxCheckedListBoxclbComboBoxcbbListViewlvwTreeViewtvwTabControltclDateTimePickerdtpMonthCalendarmcrHScrollBarhsbVScrollBarvsbTimertmrSplitterslrDomainUpDowndudNumericUpDownnudTrackBartkrProgressBarpbrRichTextBoxrtbImageListiltHelpProviderhprToolTipttpContextMenucmuToolbartbrStatusBarsbrNotifyIconninOpenFileDialogofdlgSaveFileDialogsfdlgFolderBrowserDialogfbdlgFontDialogftdlgColorDialogcrdlgPrintDialogptdlgPrintPriviewDialogppdlgPrintPriviewControlppctlErrorProvidereprPrintDocumentpdtPageSetupDialogpsdlgCrystalReportViewercrv（3）未在以上列表的控件，可以自定义前缀，或者使用全名作为前缀。4 注释和内嵌文档4.1 文件头部 每一个文件的头部要添加：#region Copyright spsp., 2003/ 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/#endregion4.2 使用#region 标注一组相关的非公共成员4.3 类的注释/作用：/作者：作者/编写日期：/如果模块有修改，则每次修改必须添加以下注释：/Log编号：/修改描述：/作者：修改者中文名/修改日期：/4.4 类属性注释规范在类的属性必须以以下格式编写属性注释：/ /属性说明/ 4.5 方法注释规范在类的方法声明前必须以以下格式编写注释/ / 说明：/ / param name=/ / / 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, IMyInterfaceint myInt;public MySample(int myInt)this.myInt = myInt ;void Inc()+myInt;void EmptyMethod()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) 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();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）声明之间（尽量将每个类分别放入不同的源代码文件，以避免这种情况） 类以及接口声明中的逻辑段落之间 函数之间（method） 属性之间（property） 一个函数中局部变量和函数的第一个表达式之间 函数中的逻辑段落之间7.2 空格逗号和分号后应加入一个空格（Space）。例如：TestMethod(a, b, c);而不是：TestMethod(a,b,c);TestMethod( a, b, c );除非特例（参见特例情况），算术、逻辑运算符两端应各加入一个空格（Space）。例如：a = b;i 10而不是：a=b;i10;特例情况：增量运算符两端不加入空格。例如：+i加入空格后逻辑上不合理的情况8 编码准则8.1 可见性（1）除非特例（参见特例情况），将类所有成员变量的可见性定义为私有。（2）使用公有或者保护的properties访问类的成员变量。（3）推荐不显式写出“private”关键字，C#中默认的可见性为私有。 （4）特例情况：静态值域(static fields)的可见性可以定义为公有。8.2 Magic Number（1）不要使用魔数(magic number)。（2）使用常量代替之。例如：public class MyMathpublic const double PI = 3.14159;8.3 异常处理（1）捕捉特定的异常，而不要捕捉一般的异常。（2）不要捕捉而不处理异常。（3）发生异常时，给出友好的消息给用户，但要精确记录错误的所有可能细节，包括发生的时间，和相关方法，类名等。（4）如果必要，可以编写自己的异常类。（5）自定义异常应实现IApplicationException，而不是派生SystemException。8.4 其他（1）在代码中应该使用相对路径，而不是使用具体的路径和驱动器名。（2）错误消息应该帮助