目 录
1 概述
dotShare系统改造项目的建设过程中,将涉及到Visual Studio.NET、Web站点,业务对象及数据库,同时项目人员包括设计人员、开发人员和测试人员等较多。为了保持应用程序、组件、文件的一致性,便于阅读和管理代码和结构,提高开发效率和产品的标准化,特制订一套开发规范和标准(包括命名规范和编码规范)。好的编码约定可使源代码严谨、可读性强且语意清楚,做到与其它语言约定相一致,并且提高直观性。希望设计/开发人员严格遵守此套开发规范和标准,并落实到自己的设计与代码程序中。
命名规范将包括:编程命名规范,业务对象命名规范,数据库命名规范,Web站点结构命名规范等。
编码规范将包括:C#编码规范,第三方模块使用规范等
本命名规范主要针对使用Visual Stdio.Net(VB.NET语言及C#语言)规范,即编程命名规范部分。请注意:在本项目过程中,C#将作为首选语言,如非特别必要,不要选用VB.NET。
2 变量命名的总原则
变量命名的总原则是一个通用性的原则,本规范后续章节中的命名规则都应当符合这些总原则。
2.1 一般性规则
· 变量名称应当准确完整地描述了变量的含义
· 名称应当反映了业务上的问题而不是技术上或编程上的解决方法
· 名称的长度应当足够长
· 名称的最后一部分应当有限定符
· 应当用Count, Index或Nbr代替Num, No.
2.2 对特定类型数据的命名
· 循环计数变量的的名称应当有含义(如果循环语句的长度超过了两行或者存在着嵌套循环,尽量避免使用I,j,k之类的变量,应该使用有意义的变量)
· 临时变量的命名应当有意义
· 所有布尔型变量的命名能够直接从名称上看出为真的条件
· 枚举类型的变量名称应当包含了基础类型,能够方便的分辨变量的类型。例如:用Color变量表示 ColorRed, ColorGreen枚据类型的值。
· 命名的常量应当代表了抽象的实体而非他们所代表的值
· 从变量命名中应当可以看出变量的作用域是局部变量,模块变量或者全局变量
· 变量的名称中不同的单词首字母要大写,以方便阅读
2.3 关于短名称的使用
· 如果不是绝对必须,尽量避免使用短的名称
· 如果变量中单词的缩写只能缩短一两个字符则使用单词的完全拼写
· 所有单词的缩写规则应当一致
2.4 其它应当避免的命名问题
· 名称具有误导性
· 两个不同的命名具有相似的含义
· 不同的命名拼写很相似,仅差一两个字符
· 在变量名称中不应当使用数字
· 完全和变量含义不相关的命名
3 Visual Stdio.Net
3.1 大写样式
使用下面的三种大写标识符约定。
将标识符的首字母和后面连接的每个单词的首字母都大写。可以对三字符或更多字符的标识符使用 Pascal 大小写。例如:
BackColor
标识符的首字母小写,而每个后面连接的单词的首字母都大写。例如:
backColor
大写
标识符中的所有字母都大写。仅对于由两个或者更少字母组成的标识符使用该约定。例如:
System.IO
System.Web.UI
可能还必须大写标识符以维持与现有非托管符号方案的兼容性,在该方案中所有大写字母经常用于枚举和常数值。一般情况下,在使用它们的程序集之外这些字符应当是不可见的。
下表汇总了大写规则,并提供了不同类型的标识符的示例。
标识符 |
大小写 |
示例 |
类 |
Pascal |
AppDomain |
枚举类型 |
Pascal |
ErrorLevel |
枚举值 |
Pascal |
FatalError |
事件 |
Pascal |
ValueChange |
异常类 |
Pascal |
WebException 注意 总是以 Exception 后缀结尾。 |
只读的静态字段 |
Pascal |
RedValue |
接口 |
Pascal |
IDisposable 注意 总是以 I 前缀开始。 |
方法 |
Pascal |
ToString |
命名空间 |
Pascal |
System.Drawing |
参数 |
Camel |
typeName |
属性 |
Pascal |
BackColor |
受保护的实例字段 |
Camel |
redValue 注意 很少使用。属性优于使用受保护的实例字段。 |
公共实例字段 |
Pascal |
RedValue 注意 很少使用。属性优于使用公共实例字段。 |
3.2 区分大小写
为了避免混淆和保证跨语言交互操作,请遵循有关区分大小写的使用的下列规则:
- 不要使用要求区分大小写的名称。对于区分大小写和不区分大小写的语言,组件都必须完全可以使用。不区分大小写的语言无法区分同一上下文中仅大小写不同的两个名称。因此,在创建的组件或类中必须避免这种情况。
- 不要创建仅是名称大小写有区别的两个命名空间。例如,不区分大小写的语言无法区分以下两个命名空间声明。
namespace ee.cummings;
namespace Ee.Cummings;
- 不要创建具有仅是大小写有区别的参数名称的函数。下面的示例是不正确的。
void MyFunction(string a, string A)
- 不要创建具有仅是大小写有区别的类型名称的命名空间。在下面的示例中,Point p 和 POINT p 是不适当的类型名称,原因是它们仅是大小写有区别。
System.Windows.Forms.Point p
System.Windows.Forms.POINT p
- 不要创建具有仅是大小写有区别的属性名称的类型。在下面的示例中,int Color 和 int COLOR 是不适当的属性名称,原因是它们仅是大小写有区别。
int Color {get, set}
int COLOR {get, set}
- 不要创建具有仅是大小写有区别的方法名称的类型。在下面的示例中,calculate 和 Calculate 是不适当的方法名称,原因是它们仅是大小写有区别。
void calculate()
void Calculate()
3.3 缩写
为了避免混淆和保证跨语言交互操作,请遵循有关区缩写的使用的下列规则:
- 不要将缩写或缩略形式用作标识符名称的组成部分。例如,使用
GetWindow
,而不要使用GetWin
。 - 不要使用计算机领域中未被普遍接受的缩写。
- 在适当的时候,使用众所周知的缩写替换冗长的词组名称。例如,用
UI
作为 User Interface 的缩写,用OLAP
作为 On-line Analytical Processing 的缩写。 - 在使用缩写时,对于超过两个字符长度的缩写请使用 Pascal 大小写或 Camel 大小写。例如,使用 HtmlButton 或 HTMLButton。但是,应当大写仅有两个字符的缩写,如,
System.IO
,而不是System.Io
。 - 不要在标识符或参数名称中使用缩写。如果必须使用缩写,对于由多于两个字符所组成的缩写请使用 Camel 大小写,虽然这和单词的标准缩写相冲突。
3.4 措词
避免使用与常用的 .NET 框架命名空间重复的类名称。例如,不要将以下任何名称用作类名称:System、Collections、Forms 或 UI。有关 .NET 框架命名空间的列表,请参阅类库。
另外,避免使用和以下关键字冲突的标识符。
AddHandler |
AddressOf |
Alias |
And |
Ansi |
As |
Assembly |
Auto |
Base |
Boolean |
ByRef |
Byte |
ByVal |
Call |
Case |
Catch |
Cbool |
CByte |
CChar |
CDate |
CDec |
CDbl |
Char |
CInt |
Class |
CLng |
Cobj |
Const |
CShort |
CSng |
CStr |
Ctype |
Date |
Decimal |
Declare |
Default |
Delegate |
Dim |
Do |
Double |
Each |
Else |
ElseIf |
End |
Enum |
Erase |
Error |
Event |
Exit |
ExternalSource |
False |
Finalize |
Finally |
Float |
For |
Friend |
Function |
Get |
GetType |
Goto |
Handles |
If |
Implements |
Imports |
In |
Inherits |
Integer |
Interface |
Is |
Let |
Lib |
Like |
Long |
|
Me |
Mod |
Module |
MustInherit |
MustOverride |
MyBase |
MyClass |
Namespace |
New |
Next |
Not |
Nothing |
NotInheritable |
NotOverridable |
Object |
On |
Option |
Optional |
Or |
Overloads |
Overridable |
Overrides |
ParamArray |
Preserve |
Private |
Property |
Protected |
Public |
RaiseEvent |
ReadOnly |
ReDim |
Region |
REM |
RemoveHandler |
Resume |
Return |
Select |
Set |
Shadows |
Shared |
Short |
Single |
Static |
Step |
Stop |
String |
Structure |
Sub |
SyncLock |
Then |
Throw |
To |
True |
Try |
TypeOf |
Unicode |
Until |
Volatile |
When |
While |
With |
WithEvents |
WriteOnly |
Xor |
eval |
extends |
instanceof |
Package |
var |
|
|
3.5 避免类型名称混淆
不同的编程语言使用不同的术语标识基本托管类型。类库设计人员必须避免使用语言特定的术语。请遵循本节中描述的规则以避免类型名称混淆。
使用描述类型的含义的名称,而不是描述类型的名称。如果参数除了其类型之外没有任何语义含义,那么在这种罕见的情况下请使用一般性名称。例如,支持将各种数据类型写入到流中的类可以有以下方法。
[Visual Basic]
Sub Write(value As Double);
Sub Write(value As Single);
Sub Write(value As Long);
Sub Write(value As Integer);
Sub Write(value As Short);
[C#]
void Write(double value);
void Write(float value);
void Write(long value);
void Write(int value);
void Write(short value);
不要创建语言特定的方法名称,如下面的示例所示。
[Visual Basic]
Sub Write(doubleValue As Double);
Sub Write(singleValue As Single);
Sub Write(longValue As Long);
Sub Write(integerValue As Integer);
Sub Write(shortValue As Short);
[C#]
void Write(double doubleValue);
void Write(float floatValue);
void Write(long longValue);
void Write(int intValue);
void Write(short shortValue);
如果有必要为每个基本数据类型创建唯一命名的方法,那么在这种极为罕见的情况下请使用通用类型名称。下表列出基本数据类型名称和它们的通用替换。
C# 类型名称 |
Visual Basic 类型名称 |
JScript 类型名称 |
Visual C++ 类型名称 |
Ilasm.exe 表示形式 |
通用类型名称 |
sbyte |
Sbyte |
sByte |
char |
int8 |
SByte |
byte |
Byte |
byte |
unsigned char |
unsigned int8 |
Byte |
short |
Short |
short |
short |
int16 |
Int16 |
ushort |
UInt16 |
ushort |
unsigned short |
unsigned int16 |
UInt16 |
int |
Integer |
int |
int |
int32 |
Int32 |
uint |
UInt32 |
uint |
unsigned int |
unsigned int32 |
UInt32 |
long |
Long |
long |
__int64 |
int64 |
Int64 |
ulong |
UInt64 |
ulong |
unsigned __int64 |
unsigned int64 |
UInt64 |
float |
Single |
float |
float |
float32 |
Single |
double |
Double |
double |
double |
float64 |
Double |
bool |
Boolean |
boolean |
bool |
bool |
Boolean |
char |
Char |
char |
wchar_t |
char |
Char |
string |
String |
string |
String |
string |
String |
object |
Object |
object |
Object |
object |
Object |
例如,支持将从流读取各种数据类型的类可以有以下方法。
[Visual Basic]
ReadDouble()As Double
ReadSingle()As Single
ReadInt64()As Long
ReadInt32()As Integer
ReadInt16()As Short
[C#]
double ReadDouble();
float ReadSingle();
long ReadInt64();
int ReadInt32();
short ReadInt16();
前面的示例优于下面的语言特定的替换。
[Visual Basic]
ReadDouble()As Double
ReadSingle()As Single
ReadLong()As Long
ReadInteger()As Integer
ReadShort()As Short
[C#]
double ReadDouble();
float ReadFloat();
long ReadLong();
int ReadInt();
short ReadShort();
3.6 命名空间命名指南
命名命名空间时的一般性规则是使用公司名称,后跟技术名称和可选的功能与设计,如下所示。
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
命名空间。