C#
编码及命名规范
为了避免混淆和保证跨语言交互操作,请遵循有关区缩写的使用的下列规则:
2007-8-20
文件类型:项目管理(标准/规范/模板)
文件编号
:
SD
-0
7
-0
1
版 本
:
1
.0
本文件版权属于北京
BRKS
,保留所有权利。
本文件中包含的信息属于北京
BRKS
的资产及机密,文件中的任何部分未经授权不得以任何形式复制
(
包括复印及以电子文本的形式传播
)
。
B.版本历史
V 版本号
|
修订日期
|
作者
|
描述
|
1.0
|
2007-08-20
|
BRKS
|
创建文档
|
|
|
|
|
|
|
|
|
C
.分发范围
本文档分发范围包括:公司技术部门管理人员、开发人员、项目管理人员。
本文档为使用
C#
进行开发的程序员提供编码规范的指导,其提供的一些编码通用规则也可以供使用其他语言编程的开发者参考。
2.1 C#
源文件
尽量保持类文件的简短,最好不要超过
2000
行,每个类分别存放在单独的文件中,文件名称
=
类名称
+ .cs
每个命名空间对应一个目录
. (
例如命名空间
GIS.MyMedia.Web.UI
对应目录为
GIS/MyMedia/Web/UI
,这样可以方便的根据命名空间找到其相应的目录。
当代码一行写不下时,参考如下规则换行:
-
在逗号后面换行
.
-
在操作符后面换行
.
-
对于表达式选用高级别处换行,而不要在低级别处换行
-
新行表达式应该与上一行同一级别的该表达式对齐
方法调用换行示例
:
longMethodCall(expr1, expr2,
expr3, expr4, expr5);
算术表达式换行示例
:
最佳风格
:
Var = a * b / (c - g + f) +
4 * z;
不良风格
:
var = a * b / (c - g +
f) + 4 * z;
第一个编码为最佳风格,因为其在括号外换行,使用了高级别处换行的规则
.
注意在排版时,整个表达式前面的空白使用
Tab
,表达式内部的空白使用空格
> var = a * b / (c - g + f) +
> ......4 * z;
'>'
代表
tab
,
'.'
代表空格
.
使用Tab键而不要使用空格来作为排版的缩进字符,使用Tab有如下好处:
-
Tab
键只有一个字符,减少击键次数。
-
如果你想增加或者减少缩排的空间,可以选定需要缩排的代码块,然后使用
Tab
增加缩排空间,使用
Shift-Tab
减少缩排空间
.
尽量避免使用大块注释. 对于代码描述使用C#推荐的///描述格式.如果你想使用块注释建议使用如下风格:
/* Line 1
* Line 2
* Line 3
*/
这种注释风格在视觉上和代码区分开来
在注释后应该紧跟一个空白行。
在注释后应该紧跟一个空白行。
使用
//
作为单行注释
一般注释的文本长度最好不要超过代码的长度,如果一行代码需要很多的文本来解释,往往说明该代码过于复杂而可能存在
Bug
。
.net支持注释文档,通过在编译选项中指定XML的文件名称,可以让VS.net自动生成注释文档.这些注释都是包含特定的XML标签。
单行注释风格如下,例如:
/// <summary>
/// This class...
/// </summary>
多行注释风格如下
:
/// <exception cref=”BogusException”>
/// This exception gets thrown as soon as a
/// Bogus flag gets set.
/// </exception>
所有的
xml
注释必须以三个
/
开头。
Ndoc
或者类似工具可以根据该注释文档生成
.chm
的帮助文件
一个声明对应于一行,这样可以方便注释,
int level; // indentation level
int size; // size of table
定义的命名必须清晰的代表该变量的含义,命名规则参见本文件
[8
命名约定
]
尽量在定义时初始化,如下:
string name = myObject.Name;
int val = time.Hours;
注意:如果在代码中引用并初始化对话框类,则应该使用语法:
using (OpenFileDialog openFileDialog = new OpenFileDialog())
{
...
}
编写类及接口时,遵循如下规则
:
不要在方法名称及圆括号间使用空格
大括号“
{
”应该出现在定义的下一行,“
{
”及“
}
”单独占一行
每行应该仅包含一个语句.
返回语句不要使用最外面的圆括号
Don't use :
return (n * (n + 1) / 2);
use :
return n * (n + 1) / 2;
if, if-else
,
if else-if else
语句应该按照如下示例使用
:
if (condition)
{
DoSomething();
...
}
if (condition)
{
DoSomething();
...
}
else
{
DoSomethingOther();
...
}
if (condition)
{
DoSomething();
...
}
else if (condition)
{
DoSomethingOther();
...
}
else
{
DoSomethingOtherAgain();
...
}
使用
for
语句的格式
:
for (int i = 0; i < 5; ++i)
{
...
}
空白的
for
语句:
for (initialization; condition; update);
foreach
使用格式
:
foreach (int i in IntList)
{
...
}
注意
:
即便是循环语句仅一行代码,也要使用括号
while
语句格式
:
while (condition)
{
...
}
空白
while
语句格式
while (condition);
do-while
语句格式
do
{
...
} while (condition);
6.6 Switch
语句
switch
语句格式
:
switch (condition)
{
case A:
...
break;
case B:
...
break;
default:
...
break;
}
try-catch
语句格式:
try
{
...
}
catch(Exception)
{
}
or
try
{
...
}
catch(Exception e)
{
...
}
or
try
{
...
}
catch(Exception e)
{
...
}
finally
{
...
空白行可以提高可读性
.
如下情况使用两个空白行
:
-
源文件的逻辑章节
-
类及接口的定义(如果一个文件包含多个类及接口,可以使用一类一个文件的规则避免这种情况)
如下情况使用一个空白行
:
-
方法之间
-
属性之间
-
方法内部的变量声明及其初始化
-
方法类部之间的不同逻辑块
逗号或者分号后面紧跟一个空格
:
TestMethod(a, b, c);
或:
TestMethod( a, b, c );
不要使用
: TestMethod(a,b,c)
操作符前后都应该使用一个空格(一元操作符入出外,如自加
/
自减,逻辑与):
a = b; // don't use a=b;
for (int i = 0; i < 10; ++i) // don't use for (int i=0; i<10; ++i)
// or
// for(int i=0;i<10;++i)
逻辑块内的多行代码应该格式化为表格格式
:
string name = "Mr. Ed";
int myValue = 5;
Test aTest = Test.TestYou;
8.1.1 Pascal
规则
每个单词开头的字母大写
(
如
T
est
C
ounter
).
8.1.2 Camel
规则
除了第一个单词外的其他单词的开头字母大写. 如. test
Counter.
8.1.3 Upper
规则
仅用于一两个字符长的常量的缩写命名
,
超过三个字符长度应该应用
Pascal
规则
.
public class Math
{
public const PI = ...
public const E = ...
public const FeigenBaumNumber = ...
}
所有命名都应该尽可能使用完整的词,例如
SpellCheck。缩写词可能有许多种形式,因此可能产生混淆。请注意:缩写词可能很难理解。如果整个单词太长,则使用完整的第一音节或经过仔细选择的缩写词。
为了避免混淆和保证跨语言交互操作,请遵循有关区分大小写的使用的下列规则:
-不要使用要求区分大小写的名称。对于区分大小写和不区分大小写的语言,组件都必须完全可以使用。不区分大小写的语言无法区分同一上下文中仅大小写不同的两个名称。因此,在创建的组件或类中必须避免这种情况。
-不要创建仅是名称大小写有区别的两个命名空间。例如,不区分大小写的语言无法区分以下两个命名空间声明。
namespace ee.cummings;
namespace Ee.Cummings;
namespace ee.cummings;
namespace Ee.Cummings;
-不要创建具有仅是大小写有区别的参数名称的函数。下面的示例是不正确的。
void MyFunction(string a, string A)
void MyFunction(string a, string A)
-不要创建具有仅是大小写有区别的类型名称的命名空间。在下面的示例中,
Point p 和 POINT p 是不适当的类型名称,原因是它们仅在大小写方面有区别。
System.Windows.Forms.Point p
System.Windows.Forms.POINT p
System.Windows.Forms.Point p
System.Windows.Forms.POINT p
-不要创建具有仅是大小写有区别的属性名称的类型。在下面的示例中,
int Color 和 int COLOR 是不适当的属性名称,原因是它们仅在大小写方面有区别。
int Color {get, set}
int COLOR {get, set}
int Color {get, set}
int COLOR {get, set}
-不要创建具有仅是大小写有区别的方法名称的类型。在下面的示例中,
calculate 和 Calculate 是不适当的方法名称,原因是它们仅在大小写方面有区别。
void calculate()
void Calculate()
void calculate()
void Calculate()
为了避免混淆和保证跨语言交互操作,请遵循有关区缩写的使用的下列规则:
- 不要将缩写或缩略形式用作标识符名称的组成部分。例如,使用
GetWindow
,而不要使用
GetWin
。
- 不要使用计算机领域中未被普遍接受的缩写。
- 在适当的时候,使用众所周知的缩写替换冗长的词组名称。例如,用
UI
作为 User Interface 的缩写,用
OLAP
作为 On-line Analytical Processing 的缩写。
- 在使用缩写时,对于超过两个字符长度的缩写,请使用 Pascal 大小写或 Camel 大小写。例如,使用 HtmlButton 或 htmlButton。但是,应当大写仅有两个字符的缩写,如,
System.IO
,而不是
System.Io
。
- 不要在标识符或参数名称中使用缩写。如果必须使用缩写,对于由多于两个字符所组成的缩写请使用 Camel 大小写,虽然这和单词的标准缩写相冲突。
-
类名应该为名词及名词短语,尽可能使用完整的词
.
-
使用
Pascal
规则
-
不要使用类前缀
-不要使用下划线字符 (_)。
-不要使用下划线字符 (_)。
-有时候需要提供以字母
I 开始的类名称,虽然该类不是接口。只要 I 是作为类名称组成部分的整个单词的第一个字母,这便是适当的。例如,类名称 IdentityStore 就是适当的。
-在适当的地方,使用复合单词命名派生的类。派生类名称的第二个部分应当是基类的名称。例如,
ApplicationException 对于从名为 Exception 的类派生的类是适当的名称,原因是 ApplicationException 是一种 Exception。请在应用该规则时进行合理的判断。例如,Button 对于从 Control 派生的类是适当的名称。尽管按钮是一种控件,但是将 Control 作为类名称的一部分将使名称不必要地加长。
-
接口名称应该为名词及名词短语或者描述其行为的形容词,尽可能使用完整的词
. (Example
IComponent
or
IEnumberable
)
-
使用
Pascal
规则
-
使用字符
I
为前缀,并紧跟一个大写字母(即接口名的第一个字母大写)
-对于
Enum 类型和值名称使用 Pascal 大小写。
-少用缩写。
-不要在
Enum类型名称上使用
Enum
后缀。
-对大多数
Enum类型使用单数名称,但是对作为位域的 Enum类型使用复数名称。
-总是将
FlagsAttribute添加到位域 Enum类型。
-
静态常量使用名词及名词短语
-
使用
Pascal
规则
-
使用描述性的命名,名称应该明确表达参数的意义及类型,优先满足参数的意义描述
-
使用
Camel
规则
-不要对字段名或静态字段名应用前缀。具体说来,不要对字段名称应用前缀来区分静态和非静态字段。例如,应用
- Web UI 类的变量命名使用如下规则
g_
或
s_
前缀是不正确的。
- Web UI 类的变量命名使用如下规则
n
Input TextBox
类:前缀
txt+
名称(
Pascal
规则),如:
txtCustomerName;
n
Label
类(包括
div
,
span
标签):前缀
lbl+
名称(
Pascal
规则),如:
lblCustomerName;
n
Input Select
类:前缀
sel+
名称(
Pascal
规则),如:
selCustomerType;
n
Input Radio
类:前缀
rdo+
名称(
Pascal
规则),如:
rdoSubscribe;
n
Input CheckBox
类:前缀
chk+
名称(
Pascal
规则),如:
chkTV
n
DataGrid
类:前缀
grd+
名称(
Pascal
规则)
,
如
grdCustomerList
n
Button
类:前缀
btn+
名称
(Pascal
规则
),
如:
btnSubmit
n
Form
类:任何一个页面最好只有一个
Form
,并且统一命名为
thisForm;
而且该
Form
起始于
<Body>
标签之前,止于
</Body>
后
-
在简单的循环语句中
计数器变量使用
i, j, k, l, m, n
-
使用
Camel
命名规则
-
使用
Pascal
规则
-对方法名采用一致的动词
/宾语或宾语/动词顺序。例如,将动词置于前面时,所使用的名称诸如 InsertWidget 和 InsertSprocket;将宾语置于前面时,所使用的名称诸如 WidgetInsert 和 SprocketInsert。
-
推荐
名称应该为动词或动词短语
.
例如
Save
,
SaveCustomer
,而不要使用
CustomerSave
- 不要在方法中重复类的名称。例如,如果某个类已命名为
Book,则不要将某个方法称为 Book.CloseBook,而可以将方法命名为 Book.Close。
- 名称应该为名词及名词短语
-
使用
Pascal
规则
-
对于
bool
型属性或者变量使用
Is
(
is
)作为前缀,不要使用
Flag
后缀,例如应该使用
IsDeleted,
而不要使用
DeleteFlag
- 名称应该为名词及名词短语
-
使用
Pascal
规则
-名称后面追加“Collection”
-
event handlers
命名使用
EventHandler
后缀
.
-
两个参数分别使用
sender
及
e
-
使用
Pascal
规则
-
事件参数使用
EventArgs
后缀
-
事件命名使用语法时态反映其激发的状态,例如
Changed
,
Changing.
-
考虑使用动词命名
.
标识符
|
大小写
|
示例
|
类
/结构
|
Pascal
|
AppDomain
|
枚举类型
|
Pascal
|
ErrorLevel
|
枚举值
|
Pascal
|
FatalError
|
事件
|
Pascal
|
ValueChange
|
异常类
|
Pascal
|
WebException
注意 总是以
Exception 后缀结尾。
|
只读的静态字段
|
Pascal
|
RedValue
|
接口
|
Pascal
|
IDisposable
注意 总是以
I 前缀开始。
|
集合
|
Pascal
|
CustomerCollection注意 总是以Collection结束
|
方法
|
Pascal
|
ToString
|
命名空间
|
Pascal
|
System.Drawing
|
参数
|
Camel
|
typeName
|
属性
|
Pascal
|
BackColor
|
受保护的实例字段
|
Camel
|
redValue
注意 很少使用。属性优于使用受保护的实例字段。
|
公共实例字段
|
Pascal
|
RedValue
注意 很少使用。属性优于使用公共实例字段。
|