NET编码规范之二----编码规范
文件命名
规则：
1） 出了系统要求之外的文件名的长度没有限制。然而一个有意义的名称来描述内容始终是最容易接收的。
2） 在文件名和扩展名之间应该只有一个英文句号“.”来分开，像后台代码文件名[DescriptiveName].aspx.cs 或者[DescriptiveName].aspx.vb 的除外。
3） 源文件名称应该用以下格式：
[FileName] = [DescriptiveName].[Extension]
备注：
[DescriptiveName] 是描述文件内容的有意义的名字
[Extension] 是程序默认的自己产生的或者与现有程序兼容的扩展名。例如：一个文本文件应该对应的扩展名是 .txt 而不是 .exe
示例：
C#
ConfigDataReader.cs
C# Project files:
|
Files |
Convention |
Example |
|
Class file |
[DescriptiveName].vb |
Authentication.vb |
|
VB.NET Project file |
[DescriptiveName].vbproj |
BusinessObjects.vbproj |
|
Solution files |
[DescriptiveName].sln |
BusinessObjects.sln |
|
Executable |
[DescriptiveName].exe |
ChartMaintenence.exe |
|
Dynamic link library |
[DescriptiveName].dll |
DataAccess.dll |
VB.NET
ConfigDataReader.vb
VB.NET Project files:
|
Files |
Convention |
Example |
|
Class file |
[DescriptiveName].vb |
Authentication.vb |
|
VB.NET Project file |
[DescriptiveName].vbproj |
BusinessObjects.vbproj |
|
Solution files |
[DescriptiveName].sln |
BusinessObjects.sln |
|
Executable |
[DescriptiveName].exe |
ChartMaintenence.exe |
|
Dynamic link library |
[DescriptiveName].dll |
DataAccess.dll |
文件头(FILE HEADER INFORMATION)
规则：
任何可编辑的文本编辑器（非二进制文件）的文件必须包含一个文件头信息，包括：
1） 一个文件内容的简短描述
2） 作者信息，例如：作者姓名
3） 创建日期
4） 文件修改日志，包括：作者，修改日期，修改描述
示例：
C#
C# 文件注释
////////////////////////////////////////////////////////////////////////////////
//
// File Description :
// -----------------------------------------------------------------------------
// Date Created : DD MMM YYYY (e.g. 01 Dec 2005)
// Author : <author name>, <company name>
// -----------------------------------------------------------------------------
// CHANGE HISTORY
// Date Modified : DD MMM YYYY (e.g. 01 Dec 2005)
// Changed By :
// Log ID :
// Change Description :
//
////////////////////////////////////////////////////////////////////////////////
VB.NET
VB 文件注释
''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
''
'' File Description :
'' ------------------------------------------------------------------------------
'' Date Created : DD MMM YYYY (e.g. 01 Dec 2005)
'' Author : <author name>, <company name>
'' ------------------------------------------------------------------------------
'' CHANGE HISTORY
'' Date Modified : DD MMM YYYY (e.g. 01 Dec 2005)
'' Changed By :
'' Log ID :
'' Change Description :
''
''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
命名空间
规则：
1）应该以整个项目的缩写作为开头，跟着是层次（分层结构的项目）的缩写，然后是模块名称或者命名空间。
2）命名空间应用于定义或者生命新的类型，类，接口 等。
3）命名空间应该是一个有意义的名字，最好给出功能提示。
4）应该定义命名空间层次的方式，避免引起歧义。
5）始终要声明实现文件顶部使用的命名空间。
示例：
C#
namespace OA.UserInfo.UI
{
......
}
namespace OA.DocInfo.UI
{
......
}
VB.NET
Namespace OA.UserInfo.UI
......
End Namespace
Namespace OA.DocInfo.UI
......
End Namespace
示例2：
C#
using OA.UserInfo.UI;
VB.NET
Imports OA.UserInfo.UI
类
规则:
1） 类名应该有意义，最好是给出一个类的功能提示
2） 以一个大写字母开头，其余文字首字母大写。例如：UIController ，EmployeeManager
3） 类的名字应该是描述生活中的实体，这样可以很容易的识别类，提高代码的可读性。
4） 如果一个类派生自另一个类，那么应该将基类名作为后缀名。
例如：StudentFrom是从From 类派生的。
EmployeeDataSet 是从DataSet类派生的。
5） Public,protect,private,internal 不同的访问修饰符修饰的方法或者类应该分开，分为不同的组。
6） 在类名中使用下划线是不允许的。
7） 在类名前不要使用任何前缀。
类摘要和方法头（CLASS SUMMARY AND FUNCTION HEADER）
规则:
1） 一个类必须有一个和文件头信息一样的摘要。请参考文件头信息。
2） 任何一个方法必须有一个摘要描述。请参考，注释、摘要和Region。
方法
规则：
1）一个方法名应该是一个有意义的名字，通常情况下应该以动词开始名词结束。
例如：CalculateInvoiceTotal()。
2）方法名中的每一个单词都应该以大写字母开头，其余的字母小写。
例如：GetEmployeeDetails(), GetPassword() 等等。
3）方法体包括注释，变量声明在内的所有行，应该不超过100行。
4）如果方法是bool类型的计算，或者返回值为bool类型应该以Is 作为前缀。
例如:IsWorkStationLocked()。
5） 不要使用.NET方法库中已经存在的名称。
6）每一行代码从开始到结束不应该超过100个字符，包括标签和空格。如果有超过请换行。增加可读性。
7）方法与方法之间添加一行空行。
属性
规则：
1） 一个C#中成员属性，应该有一个有意义的名称，比如描述功能或者适用于哪个领域。
2） 通常情况下，属性的名称应该是它适用的字段名称相同或描述的功能，它应该是一个有意义的名词。
3） 名称中每个单词都应该大写首字母，其余小写。
4） 重复是多余的，我们应该省去。
例如：Book.BookTitle错误，应该使用Book.Title。
5） 属性应该都有注释。请参考，注释、摘要和Region。
示例:
属性
public class Employee
{
private string strName;
public string Name
{
get
{
return strName;
}
set
{
strName = value;
}
}
}
常量
规则:
1） 所有的数值应该被定义为符号常量。所有的其他常量（字符串，bool）都应该被定义为符号常量。
2） 常量名字都应该大写，单词之间应该用下划线分割，例如：NUM_DAYS_IN_WEEK
3） 所有常量的定义都在类文件的顶部。使用配置文件在存储应用程序级的常量。
4） 使用的常量应该给以适当的注释。
示例:
const int NUM_DAYS_IN_WEEK = 7;
变量
一般规则：
1） 变量应该声明在尽量小的范围内以增强代码的可读性。
2） 每个变量都应该在声明或者第一次使用的时候初始化。
3） 由于大多数名称都是由多个单词组成，变量名应该以小写字母开始，其余单词应该大些首字母。
4） 最好不要用.NET 关键字或者方法库中的方法名称。
5） 根据他们的数据类型，应该参考下表作为前缀。
变量名及其前缀表格
| SR No. | Data Type | Prefix | Example |
| 1. | Boolean | bln | blnActiveFlag |
| 2. | Byte | byt | bytAccountType |
| 3. | Char | chr | chrRegistrationCode |
| 4. | Currency | cur | curSalesAmount |
| 5. | Date | dte | dteIssueDate |
| 6. | Decimal | dec | decGameScore |
| 7. | Double | dbl | dblMilleage |
| 8. | Integer | int | intRenewalCount |
| 9. | Long | lng | lngFileCount |
| 10. | Object | obj | objPeople |
| 11. | Short | shr | shrAccountType |
| 12. | Single | sgl | sglRevenue |
| 13. | String | str | strCompanyName |
备注：
1） 变量名能够很好的表示其功能。
2） 在变量名结尾追加计算限定符（Avg, Sum, Min, Max, Index）
3） 使用习惯中相反的词语，如开始/结束，最大/最小，打开/关闭。
4） 避免用术语‘Flag’来命名状态变量，应为状态变量可能有两个以上的值。例如：我们不用DocumnetFlag ，用DocumentFormatFlag。
5） 即使只有几行代码的临时变量，我们也要使用有意义的名称。
类成员变量
规则:
1） 所有的变量都应使用有意义的名称，不同访问修饰符的应该分开，请参考2.2.1。
2） 所有的非公共成员都应该以小写字母开头，其他单词首字母大写。
3） 成员变量应该合理的分组，提高可读性。
4） 通常情况下在类中是没有公共成员变量的，如果有请参照 类中的详细要求。
示例：
类成员变量
public class Employee
{
private string strFirstName;
private string strLastName;
private string strPassword;
protected string strSalary;
public bool GetEmployeeDetails(int intEmpId)
{
string strName = "";
}
}
可识别的标示符
下面的表格中提到了一些容易识别的前缀，当我们起名字的时候应该参考以下2点：
1）描述功能的有意义的名称
2）每一个单词首字母都应该大写
标示符及其前缀表格
| Identifier | Prefix\Suffix | Example |
| Class | None | AppDomain |
| Enum type | None | ErrorColor |
| Enum values | None | Red |
| EventHandler | Suffix EventHandler | MouseOverEventHandler |
| EventArgs | Suffix EventArgs | KeyEventArgs |
| Exception class | Suffix Exception | AppException, Note Always ends with the suffix Exception. |
| Interface | Prefix I | IBanking,Note Always begins with the prefix I. |
| Custom Attributes | Suffix Attribute | MyCustomAttribute |
| Method | None | IsCustomerIDMissing |
| Namespace | None | MyProject |
| Function Parameter | None | EmployeeName |
| Property | None | BackColor |
命名类型
在其名称的时候大小写应该参照以下类型：
1）Pascal Casing-每个单词的首字母大写，例如：BackColor
2）Camel Casing-除了第一个单词外，其他单词的首字母大写，例如：backColor
3) Upper Casing-所有字母都要大写
| Identifier | Case | Example |
| Class | Pascal | AppDomain |
| Enum type | Pascal | ErrorColor |
| Enum values | Pascal | Red |
| Variables | Camel | backColor,empId,phoneNo,personNRIC |
| Property | Pascal | BackColor |
| Method | Pascal | IsCustomerIdMissing |
| Function Parameter | Camel | employeeAge |
| Constant Variable | Upper Case | MATH_PI |
注释、摘要和Region
规则：
1） 有需要就加注释，如：有Flags 需要修改或者检查。
2） 不要在行尾加注释，在行尾加注释更不容易阅读。在发布之前移除所有的无关的注释。
3） 如果今天来不及完成的代码，请注释，明天可以继续，方便我们以后阅读。
4） 使用注释来解释代码的意思。
5） 在分支或者虚幻上边加注释，协助以后的读者阅读。
6） 在所有的比较困难或者复杂的代码块前使用注释。
7） 添加注释可以用‘//’，‘/*……*/’可能注释掉代码块外的内容。在方法头使用‘///’来添加注释。
8） 整个应用程序使用统一的风格，常量命名和结构。
9） 类，方法，属性 前面必须添加注释，增加可读性。
10）每个类应该有4个默认的Region
Member Variables
Private Method
Protect Method
Public Method
也可以由额外的region。
11）你可以在Visual Stdio 中生成XML文档说明，如果你用‘///’然后VS就能找到，这些特定元素。如果需要产生XML文档，则Rebuild 项目就可以生成。
12）尽量不要注释代码，除非这些代码你今后还打算用到。（如果注释今后打算用到的代码请在注释中添加 TODO）
示例：
C#
C#文件
//////////////////////////////////////////////////////////////////////
//
// File Description : Data Access Object for Employee.
// ----------------------------------------------------------------
// Date Created : 28 Jan 2012
// Author : XYZ, ADF
// ----------------------------------------------------------------
// CHANGE HISTORY
// Date Modified :
// Changed By :
// Log ID :
// Change Description :
//
//////////////////////////////////////////////////////////////////////
using System;
using System.Data;
namespace ASPTest
{
/// <summary>
/// This class contains all functionality and data related to an
/// employee.
/// </summary>
public class Employee : IHuman
{
#region Member Variables
private string strFirstName;
private string strLastName;
private string strPassword;
protected decimal decSalary;
#endregion
#region Public Methods
/// <summary>
/// This constructor initializes....
/// </summary>
public Employee()
{
// Code Implementation
}
/// <summary>
/// This constructor does....
/// </summary>
/// <param name="intEmpId">Employee Id</param>
public Employee(int intEmpId)
{
// Code Implementation
}
/// <summary>
/// This will remove the objects from memory.
/// </summary>
~Employee()
{
// Code Implementation
}
/// <summary>
/// Gets or Sets Password.
/// </summary>
public string Password
{
get
{
return strPassword;
}
set
{
strPassword = value;
}
}
/// <summary>
/// To get all the details of an employee.
/// </summary>
/// <param name="intEmpId">Employee Id</param>
/// <returns>Returns true/false.</returns>
public bool GetEmployeeDetails(int intEmpId)
{
// Code implementation
}
/// <summary>
/// To get all Employees from the database.
/// </summary>
/// <returns>Returns true/false.</returns>
public bool GetAllEmployees()
{
// Code Implementation
}
#endregion
}
}
浙公网安备 33010602011771号