2 编码惯例
coding practices
1. 避免在一个文件中放多个类。
avoid putting multiple classes in a single file.
2. 一个文件应该只对一个命名空间提供类型。避免在同一文件中有多个命名空间。
a single file should only contribute types to a single namespace. avoid having multiple namespaces in the same file.
3. 避免文件长度超过500行(除了机器自动产生的代码)。
avoid files with more than 500 lines (excluding machine-generated code).
4. 避免方法定义超过25行。
avoid methods with more than 25 lines.
5. 避免超过5个参数的方法。使用结构传递多个参数。
avoid methods with more than 5 arguments. use structures for passing multiple arguments.
6. 每行应该不超过80个字符。
lines should not exceed 80 characters.
7. 不要手工编辑任何机器生成的代码。
do not manually edit any machine generated code.
a) 如果修改机器生成的代码，修改代码格式和风格以符合本编码标准。
if modifying machine generated code, modify the format and style to match this coding standard.
b) 尽可能采用partial类以分解出需要维护的部分。
use partial classes whenever possible to factor out the maintained portions.
8. 避免对显而易见的内容作注释。
avoid comments that explain the obvious.
a) 代码应该是自解释的。 由可读性强的变量和方法组成的好的代码应该不需要注释。
code should be self explanatory. good code with readable variable and method names should not require comments.
9. 仅对操作的前提、内在算法等写文档。
document only operational assumptions, algorithm insights and so on.
10. 避免方法级的文档。
avoid method-level documentation.
a) 对api文档采用大量的外部文档。
use extensive external documentation for api documentation.
b) 方法级注释仅作为对其他开发人员的提示。
use method-level comments only as tool tips for other developers.
11. 决不要硬编码数值， 而总是声明一个常量。
never hard-code a numeric value, always declare a constant instead.
12. 仅对本来就是常量的值使用const修饰符，例如一周的天数。
use the const directive only on natural constants such as the number of days of week.
13. 避免对只读变量使用const修饰符。在此情况下，采用readonly修饰符。
avoid using const on read-only variables. for that, use the readonly directive.
public class myclass
{
public readonly int number;
public myclass(int somevalue)
{
number = somevalue;
}
public const int daysinweek = 7;
}
14. 对任何假设采用assert。
assert every assumption.
a) 平均地，每5行中就有一行是断言。
on average, every fifth line is an assertion.
using system.diagnostics;
object getobject()
{
object obj = getobject();
debug.assert(obj != null);
15. 每行代码应该经过白盒测试。
every line of code should be walked through in a 搘hite box?testing manner.
16. 仅捕获已经显式处理了的异常。
only catch exceptions for which you have explicit handling.
17. 在抛出异常的catch语句中，总是抛出最初异常以保持最初错误的堆栈位置。
in a catch statement that throws an exception, always throw the original exception to maintain stack location of original error.
catch(exception exception)
{
messagebox.show(exception.message);
throw; //same as throw exception;
}
18. 避免将错误代码作为方法的返回值。
avoid error code as methods return values.
19. 避免定义自定义的异常类。
avoid defining custom exception classes.
20. 定义自定义异常时：
when defining custom exceptions:
a) 从applicationexception继承
derive the custom exception from applicationexception.
b) 提供自定义的序列化。
provide custom serialization.
21. 避免在一个程序集中有多个main()方法。
avoid multiple main() methods in a single assembly.
22. 仅对最需要的类型标记为public，其他的标记为internal。
make only the most necessary types public, mark others as internal.
23. 避免采用friend程序集，因为这样增加了程序集间的耦合度。
avoid friend assemblies, as it increases inter-assembly coupling.
24. 避免使用依赖于从特定位置运行的程序集的代码。
avoid code that relies on an assembly running from a particular location.
25. 尽量减少应用程序集(客户端exe程序集)的代码。采用类库而不要包含业务逻辑层代码。
minimize code in application assemblies (exe client assemblies). use class libraries instead to contain business logic.
26. 避免对枚举提供明确的值。
avoid providing explicit values for enums .
//correct
public enum color
{
red,green,blue
}
//avoid
public enum color
{
red = 1,green = 2,blue = 3
}
27. 避免对枚举指定类型。
avoid specifying a type for an enum.
//avoid
public enum color : long
{
red,green,blue
}
28. if语句总是使用括号，即使它包含一句语句。
always use a curly brace scope in an if statement, even if it conditions a single statement.
29. 避免使用?:条件算符。
avoid using the trinary conditional operator.
30. 避免在布尔条件语句中调用函数。赋值到局部变量并检查它们的值。
avoid function calls in boolean conditional statements. assign into local variables and check on them:
bool iseverythingok()
{...}
//避免：
//avoid:
if(iseverythingok())
{...}
//采用：
//instead:
bool ok = iseverythingok();
if(ok)
{...}
31. 总是使用从0开始的数组。
always use zero-based arrays.
32. 总是使用一个for循环显式地初始化一个引用类型的数组。
always explicitly initialize an array of reference types using a for loop.
public class myclass
{}
myclass[] array = new myclass[100];
for(int index = 0; index < array.length; index++)
{
array[index] = new myclass();
}
33. 不用提供public或protected成员变量，而是使用属性。
do not provide public or protected member variables. use properties instead.
