C#编码规范.doc

C#编码规范

一． 命名规范

1. 利用Pascal的方式定义类型、方法名和常量
Pascal方式：所有单词第一个字母大写，其他字母小写
public class SomeClass
{
const int DefaultSize=100;
public SomeMethod()
{
}
}

2. 对于局部变量和方法的参数使用Camel骆驼命名法
Camel方式：除第一个单词外，所有单词第一个字母大写，其他字母小写
int number;
void MyMethod(int someNumber)
{
}

3. 接口的名称前加上I
interface IMyInterface
{
}

4. 在私有成员变量前面加上m_，对于m_后面的变量名使用骆驼命名方法
public class SomeClass
{
private int m_Number;
}

5. 对自定义的属性类加上后缀Attribute
6. 对自定义的异常类加上后缀Exception
7. 方法的命名使用动词----对象对，例如ShowDialog()
8. 有返回值的方法的命名中要有返回值的描述，例如GetObjectState()
9. 使用带有说明性的变量名
a) 避免单字符的变量名，例如I或t等。使用类似于index或temp这样有意义的名字。
b) 对于public或protected类型的变量避免使用匈牙利表示法。
c) 不要缩写单词（例如用num取代number）。
10. 总是使用C#预定义而不要使用System名称空间中的别名，例如：
使用object而不是Object
使用string而不是String
使用int而不是int32
11. 在使用泛型的时候，类型的首字母要大写。当处理.NET中的Type类型的时候，保留Type后缀。(C#2.0新特性)
//正确
public class LinkedList<K,T>
{…}
//避免
public class LinkedList<KeyType,DataType>
{….}

12. 使用有意义的名字定义名称空间，例如产品名或者公司名
13. 避免通过全限定方式使用类型名称，使用using关键字
14. 避免在一个名称空间中使用using关键字
15. 把所有系统框架提供的名称空间组织到一起，把第三方提供的名称空间放到系统名称空间的下面
using System;
using System.Collection.Generic;
using System.ComponentModel;
using System.Data;
using MyCompany;
using MyControls;

16.使用代理推导而不要显式的实例化一个化代理（C#2.0新特性）
delegate void SomeDelegate();
public void SomeMethod()
{…}
SomeDelegate someDelegate=SomeMethod;

17. 维护严格的代码缩进。不要使用tabs或非标准的缩进，例如一个空格。推荐的缩进是3到4个空格
18. 在和你的代码缩进处于同一个级别处为该行代码添加注释
19. 所有的注释都应该通过拼写检查。注释中的错误拼写意味着开发进度的延缓
20. 所有的类成员变量应该被声明在类的顶部，并用一个空行把它们和方法以及属性的声明区分开
public class MyClass
{ 
int m_Number;
string m_Name;

public void SomeMethod1();
public void SomeMethod2();
}

21. 在最靠近一个局部变量被使用的地方声明该局部变量
22. 一个文件名应该能够反映它所对应的类名
23.当使用一个部分类并把该类分布到不同的文件中时，在每一个文件名末尾都加上该文件实现的部分在类整体中扮演的作用。例如:
// In MyClass.cs
public partial class MyClass
{…}
//In MyClass.Designer.cs
public partial class MyClass
{…}

24.总是要把花括号“{”放在新的一行

Summary
Type
Case
Notes
Example
Class / Struct
Pascal Casing

AppDomain
Interface
Pascal Casing
Starts with I
IDisposable
Enum values
Pascal Casing

FatalError
Enum type
Pascal Casing

ErrorLevel
Events
Pascal Casing

ValueChange
Exception class
Pascal Casing
End with Exception
WebException
public Fields
Pascal Casing

MyListCtrl
Methods
Pascal Casing

ToString
Namespace
Pascal Casing

System.Drawing
Property
Pascal Casing

BackColor
Const Field
Pascal Casing

MaximumItemNumber
Read-only Static Field
Pascal Casing

RedValue
Protected/private Fields
Camel Casing

listItem
Parameters
Camel Casing

typeName

二．编码实践:

1. 避免在同一个文件中放置多个类
2. 一个文件应该只向在一个名称空间内定义类型。避免在一个文件中使用多个名称空间
3. 避免在一个文件内写多于500行的代码（机器自动生成的代码除外）
4. 避免写超过25行代码的方法
5. 避免写超过5个参数的方法，如果要传递多个参数，使用结构
6. 一行不要超过80个字符
7. 不要手动去修改任何机器生成的代码
a) 如果修改了机器生成的代码，修改你的编码方式来适应这个编码标准
b) 尽可能使用partial classes特性，以提高可维护性。(C#2.0新特性)
8. 避免对那些很直观的内容作注释。代码本身应该能够解释其本身的含义。由可读的变量名和方法名构成的优质代码应该不需要注释
9. 注释应该只说明操作的一些前提假设、算法的内部信息等内容
10. 避免对方法进行注释
a) 使用充足的外部文档对API进行说明
b) 只有对那些其他开发者的提示信息才有必要放到方法级的注释中来
11. 除了0和1，绝对不要对数值进行硬编码，通过声明一个常量来代替该数值
12. 只对那些亘古不变的数值使用const关键字，例如一周的天数。
13. 避免对只读(read-only)变量使用const关键字，在这种情况下，直接使用readonly关键字
public class MyClass
{
public const int DaysInWeek=7;
pubic readonly int Number;
public MyClass(int someValue)
{
Number=someValue;
}
}

14. 对每一个假设进行断言。平均起来，每5行应有一个断言
using System.Diagnostics;
object GetObject()
{
}
object someObject=GetObject();
Debug.assert(someObject!=null);

15. 每一行代码都应该以白盒测试的方式进行审读
16. 只捕捉那些你自己能够显式处理的异常
17. 如果在catch语句块中需要抛出异常，则只抛出该catch所捕捉到的异常（或基于该异常而创建的其他异常），这样可以维护原始错误所在的堆栈位置
catch(Exception exception)
{
MessageBox.Show(exception.Message);
throw;//或throw exception;
}

18. 避免利用返回值作为函数的错误代码
19. 避免自定义异常类
20. 当自定义异常类的时候
a) 让你自定义的异常类从Exception类继承
b) 提供自定义的串行化机制
21. 避免在一个程序集中(assembly)中定义多个Main()方法
22. 只把那些绝对需要的方法定义成public,而其它的方法定义成internal
23. 避免friend assemblies，因为这会增加程序集之间的耦合性
24. 避免让你的代码依赖于运行在某个特定地方的程序集
25. 在application assembly(EXE client assemblies)中最小化代码量，使用类库来包含业务逻辑
26. 避免显式指定枚举的值
//正确
public enum Color
{
Red,Green,Blue
}

//避免
public enum Color
{
Red=1,Green=2,Blue=3
}

27. 避免为枚举指定一个类型
//避免
public enum Color:long
{
Red,Green,Blue
}

28. 对于if语句，总使用一对{}把下面的语句块包含起来，哪怕只有一条语句也是如此
29. 避免使用三元条件操作符
30. 避免利用函数返回的Boolean值作为if语句的条件，而应该将返回值赋给一个局部变量，然后再检测，例如：
Bool IsEverythingOK()
{…}

//避免
if(IsEverythingOk())
{…}

//正确
bool ok=IsEverythingOK();
if (ok)
{…}

31. 总是使用以零为基数的数组
32. 总是使用一个for循环显式的初始化一个引用成员的数组
[quote]public class MyClass
{}

const int ArraySize=100;
MyClass[] array=new MyClass[ArraySize];
for(int index=0;index<array.Length;index++)
{
array[index]=new MyClass();
}[/quote]

33. 使用属性来替代public或protected类型的成员变量
34. 不要使用继承下来的new操作符，而要使用override关键字覆写new的实现
35. 在一个非密封（non-sealed）类中，总是把那些public和protected的方法定义成virtual
36. 除非为了和其它语言进行互动，否则绝不要使用不安（unsafe）的代码
37. 避免显示类型转换。使用as关键字安全的转换到另一个类型
Dog dog=new GermanShepherd();
GermanShepherd shepherd=dog as GermanShepherd;
if (shepherd!=null)
{…}

38. 在调用一个代理前，总是检查它是否为null
39. 不要提供public的事件成员变量，改用Event Accessor
Public class MyPublisher
{
MyDelegate m_SomeEvent;

Public event MyDelegate SomeEvent
{
add
{
m_SomeEvent+=value;
}

Remove
{
m_SomeEvent-=value;
}
}
}

40. 避免定义事件处理代理，使用EventHandler<T>或者GenericEventHandler
41. 避免显示触发事件，使用EventsHelper安全的发布事件
42. 总是使用接口
43. 接口和类中方法和属性的比应该在2:1左右
44. 避免只有一个成员的接口
45. 努力保证一个接口有3~5个成员
46. 不要让一个接口中成员的数量超过20，而12则是更为实际的限制
47. 避免在接口中包含事件
48. 当使用抽象类的时候，提供一个接口
49. 在类继承结构中暴露接口
50. 推荐使用显式接口实现
51. 从来不要假设一个类型支持某个接口，在使用前总是要询问一下
SomeType obj1;
ImyInterface obj2;

/*Some code to initialize obj1,then:*/
obj2=obj1 as ImyInterface;
if(obj2!=null)
{
obj2.Method1();
}
else
{
//Handle erro in expected interface
}

52. 不要硬编码向用户显示字符串，要使用资源
53. 不要硬编码那些可能会随发布环境变化而变化的字符串，例如数据库连接字符串
54. 使用String.Empty取代””
//避免
string name=””;

//正确
string name=String.Empty;

55. 使用一个长字符串的时候，使用StringBuilder代替string
56. 避免在结构中提供方法
a) 参数化的构造函数是鼓励使用的
b) 可以重载运行符
57. 当声明了静态成员的时候，总是要提供一个静态构造函数
58. 当早绑定(early-binding)可能的时候就尽量不要使用迟绑定（late-binding）
59. 让你的应用程序支持跟踪和日志
60. 除了要在switch语句块中实现代码跳转，不要使用goto关键字
61. 总在switch语句的default情形提供一个断言
int number=SomeMethod();
swith(number)
{
case 1:
trace.WriteLine(“Case 1:”)
break;
case 2:
trace.Writeline(“Case 2:”)
default:
debug.Assert(false);
dreak;
}

62. 除了在一个构造函数中调用其它的构造函数之外，不要使用this关键字
//Example of proper use of ‘this’
public class MyClass
{
public MyClass(string message)
{
}

public MyClass():this(“Hello”)
{
}
}

63. 不要使用base关键字访问基类的成员，除非你在调用一个基类构造函数的时候要决议一个子类的名称冲突
//Example of proper use of ‘base’
public class Dog
{
public Dog(string name)
{
}

virtual public void Bark(int howlong)
{
}
}

public class GermanShepherd:Dog
{
public GermanShepherd(string name):base(name)
{
}

override public void Bark(int howLong)
{
base.Bark(howLong)
}
}

64. 不要使用GC.AddMemoryPressure()
65. 不要依赖HandleCollector
66. 基于《Programming .NET components》2/e中第四章的内容实现Disponse()和Finalize()方法
67. 总是在unchecked状态下运行代码(出于性能的原因)，但是为了防止溢出或下溢操作，要果断地使用checked模式
int CalcPower(int number,int power)
{
int result=1;
for (int count=1;count<=power;count++)
{
checked
{
result*=number;
}
}

return result;
}

68. 使用条件方法来取代显式进行方法调用排除的代码(#if…#endif)
[quote]public class MyClass
{
[Conditional(“MySpecialCondition”)]
public void MyMethod()
{
}
}[/quote]

69. 不要在泛型接口中定义约束，接口级的约束通常可以利用强类型来替代
public class Customer
{}

//避免:
public interface Ilist<T> where T:Customer
{}
//正确:
public interface IcustomerList:Ilist<Customer>

70. 不要在接口上定义方法相关的约束
71. 不要在代理上定义约束
72. 如果一个类或方法提供了泛型和非泛型版本，那么优先选择泛型版本

三．项目设置和项目结构

1. 总是在4级警告上建立你的项目
2. 在发布版中，把警告当成错误来对待
3. 避免关闭编译器的某些警告选项
4. 总是要在应用程序的配置文件中显示指定支持的运行时版本
5. 避免显示进行CLR程序集版本的重定向和绑定
6. 避免显示的预处理定义（＃define），使用项目设置来定义条件编译常量
7. 不要在AssemblyInfo.cs中加入任何逻辑
8. 不要在AssemblyInfo.cs之外的文件中添加程序级属性
9. 提供AssemblyInfo.cs中的所有信息，例如公司名、描述和版权事项等
10. 同一个解决方案中的程序集引用都应该使用相同路径
11. 禁止在程序集之间使用循环引用
12. 避免多模块程序集
13. 避免利用异常窗口削弱异常处理
14. 坚持在同一个解决方案中的所有程序集之间使用统一的版本号
15. 把所有解决方案的信息存放到一个共享的SolutionInfo.cs文件中
16. 把你的应用程序的配置文件命名为App.config，并把它包含在你的项目中
17. 修改Visual Studio 2005 的默认项目结构来适应你的项目规划，并且对项目文件夹和文件使用统一的结构
18. 一个Release发布应该包含调试信息
19. 总是对你的程序集进行签名，包括你的客户应用程序