C# 编码标准(三)
一、代码注释
1、文档型注释
该类注释采用.Net已定义好的Xml标签来标记，在声明接口、类、方法、属性、字段都应该使用该类注释，以便代码完成后直接生成代码文档，让别人更好的了解代码的实现和接口。【示例】如
///<summary>MyMethod is a method in the MyClass class.
///<para>Here's how you could make a second paragraph in a description.
///<see cref="System.Console.WriteLine"/>
///for information about output statements.
///</para>
///<seealso cref="MyClass.Main"/>
///</summary>
publicstaticvoid MyMethod(int parameter)
{
}
注：此功能在.net的开发环境中的方法或类定义的上一行写入”///”后，系统会根据方法的声明自动生成相关的注释模板，推荐使用此方式对方法属性等添加相关的注释
二、单行注释
该类注释用于方法内的代码注释。如变量的声明、代码或代码段的解释。
【示例】：
// 注释语句----------------中间保留一个空格
privateint number;
三、 注释标签
|
标签 |
用法 |
作用 |
|
<c> |
<c>text</c> text 希望将其指示为代码的文本。 |
为您提供了一种将说明中的文本标记为代码的方法。使用 <code> 将多行指示为代码 |
|
<para> |
<para>content</para> content段落文本。 |
用于诸如 <remarks> 或 <returns> 等标记内，使您得以将结构添加到文本中。 |
|
<param> |
<param name='name'>description</param> name 为方法参数名。将此名称用单引号括起来 (' ')。 |
应当用于方法声明的注释中，以描述方法的一个参数。 |
|
<paramref>
|
<paramref name="name"/> name 要引用的参数名。将此名称用双引号括起来 (" ")。 |
<paramref> 标记为您提供了一种指示词为参数的方法。可以处理 XML 文件，从而用某种独特的方法格式化该参数。 |
|
<see> |
<see cref="member"/>
cref = "member" 对可以通过当前编译环境进行调用的成员或字段的引用。编译器检查到给定代码元素存在后，将 member 传递给输出 XML 中的元素名。必须将 member 括在双引号 (" ") 中。 |
使您得以从文本内指定链接。使用 <seealso> 指示希望在“请参阅”一节中出现的文本。 |
|
<seealso> |
<seealso cref="member"/>
cref = "member" 对可以通过当前编译环境进行调用的成员或字段的引用。编译器检查到给定代码元素存在后，将 member 传递给输出 XML 中的元素名。必须将 member 括在双引号 (" ") 中 |
使您得以指定希望在“请参阅”一节中出现的文本。使用 <see> 从文本 |
|
<example> |
<example>description</example> description 代码示例的说明。 |
使用 <example> 标记可以指定使用方法或其他库成员的示例。一般情况下，这将涉及到 <code> 标记的使用。 |
|
<code> |
<code>content</code>
content 为希望将其标记为代码的文本。
|
记为您提供了一种将多行指示为代码的方法。使用 <c> 指示应将说明中的文本标记为代码 |
|
<summary> |
<summary>description</summary>
此处description 为对象的摘要。 |
应当用于描述类型成员。使用 <remarks> 以提供有关类型本身的信息。 |
|
<exception> |
<exception cref="member">description</exception> cref = "member" 对可从当前编译环境中获取的异常的引用。编译器检查到给定异常存在后，将 member 转换为输出 XML 中的规范化元素名。必须将 member 括在双引号 (" ") 中。 description 说明。 |
<exception> 标记使您可以指定类能够引发的异常。 |
|
<include> |
<include file='filename' path='tagpath[@name="id"]' /> filename 包含文档的文件名。该文件名可用路径加以限定。将 filename 括在单引号中 (' ')。 Tagpath：filename 中指向标记名的标记路径。将此路径括在单引号中 (' ')。 name 注释前边的标记中的名称说明符；名称具有一个 id。 id 位于注释之前的标记的 id。将此 id 括在双引号中 (" ")。 |
<include> 标记使您得以引用描述源代码中类型和成员的另一文件中的注释。这是除了将文档注释直接置于源代码文件中之外的另一种可选方法。 <include> 标记使用 XML XPath 语法。有关自定义 <include> 使用的方法，请参阅 XPath 文档。 |
|
<list> |
<list type="bullet" | "number" | "table"> <listheader> <term>term</term> <description>description</description> </listheader> <item> <term>term</term> <description>description</description> </item> </list> term 定义的项，该项将在 text 中定义。
description 目符号列表或编号列表中的项或者 term 的定义。 |
<listheader> 块用于定义表或定义列表中的标题行。定义表时，只需为标题中的项提供一个项。 列表中的每一项用 <item> 块指定。创建定义列表时，既需要指定 term 也需要指定 text。但是，对于表、项目符号列表或编号列表，只需为 text 提供一个项。 列表或表所拥有的 <item> 块数可以根据需要而定。 |
|
<permission> |
<permission cref="member">description</permission>
cref = "member" 对可以通过当前编译环境进行调用的成员或字段的引用。编译器检查到给定代码元素存在后，将 member 转换为输出 XML 中的规范化元素名。必须将 member 括在双引号 (" ") 中。 description 成员的访问的说明。 |
<permission> 标记使您得以将成员的访问记入文档。System.Security.PermissionSet 使您得以指定对成员的访问。 |
|
<remarks> |
<remarks>description</remarks>
description 成员的说明。 |
<remarks> 标记是可以指定有关类或其他类型的概述信息的位置。<summary> 是可以描述该类型的成员的位置。 |
|
<returns> |
<returns>description</returns> description 返回值的说明。 |
<returns> 标记应当用于方法声明的注释，以描述返回值。 |
|
<value> |
<value>property-description</value> property-description 属性的说明。 |
<value> 标记使您得以描述属性。请注意，当在 Visual Studio .NET 开发环境中通过代码向导添加属性时，它将会为新属性添加 <summary> 标记。然后，应该手动添加 <value> 标记以描述该属性所表示的值。 |
四、变量声明
1、一行只建议作一个声明，并按字母顺序排列：
int level; //推荐 int size; //推荐 int x, y; //不推荐
五、命名方法
1.所有的命名（包括标识符，类，接口，函数等等）使用有意义的英文标识符，不允许使用汉语拼音，也不允许使用中文作为各种命名。
2.避免容易被主观解释的难懂的名称，如方面名 AnalyzeThis()，或者属性名 xxK8。这样的名称会导致多义性。
3、在类属性的名称中包含类名是多余的，如 Book.BookTitle。而是应该使用 Book.Title。
4、只要合适，在变量名的末尾或开头加计算限定符（Avg、Sum、Min、Max、Index）。
5、在变量名中使用互补对，如 min/max、begin/end 和 open/close。
6、布尔变量名表示是否时可以包含 Is，这意味着 Yes/No 或 True/False 值，如 fileIsFound。
7、即使对于可能仅出现在几个代码行中的生存期很短的变量，仍然使用有意义的名称。仅对于短循环索引使用单字母变量名，如 i 或 j。
六、附录
1、控件相关命名,红色是常用控件
|
控件名 |
简写 |
控件名 |
简写 |
|
Label |
lbl |
TextBox |
txt |
|
Button |
btn |
LinkButton |
lnkbtn |
|
ImageButton |
imgbtn |
DropDownList |
ddl |
|
ListBox |
lst |
DataGridView |
dgv |
|
DataList |
dl |
CheckBox |
chk |
|
CheckBoxList |
chkls |
RadioButton |
rdo |
|
RadioButtonList |
rdolt |
Image |
img |
|
Panel |
pnl |
Calender |
cld |
|
AdRotator |
ar |
Table |
tbl |
|
RequiredFieldValidator |
rfv |
CompareValidator |
cv |
|
RangeValidator |
rv |
RegularExpressionValidator |
rev |
|
ValidatorSummary |
vs |
CrystalReportViewer |
rptvew |
|
ListView |
lst |
DataGrid |
dg |
2 常见集合类型后缀命名
凡符合下表所列的集合类型，应添加相应的后缀。
| 说明 | 后缀 | 示例 | |
| 数组 | Array 或 s | int[] productArray 或 int[] products | |
| 列表 | List 或 s | List<Product> productList 或 List<Product> products | |
| DataTable/HashTable | Table | HashTable productTable | |
| 字典 | Dictionary 或 Dic | Dictionay<string,string> productDictionary 或 Dictionay<string,string> productDic | |
| DbSet /DataSet | Set 或DataSet | DbSet<Product> productSet 或 DbSet<Product> productDataSet | |
| 集合 | Coll 或 s 或 Collection | TableCollection tables 或 TableCollection tableColl 或 TableCollection tableCollection |
凡符合下表所列的局部变量、方法参数、字段、属性，均需添加相应的后缀。
| 后缀 | 示例 | 示例说明 | |
| 费用相关 | Cost | ShipCost | 运输费 |
| 价格相关 | Price | ProductUnitPrice | 产品单价 |
| 消息相关 | Message | SuccessMessage | 成功消息 |
| 日期相关 | Date | OrderDate | 下单日期 |
| 计数、数量相关 | Count | LoginCount | 登录次数 |
| 链接地址相关 | Url | BlogUrl | 博客链接 |
| 图片相关 | Image | SignImage | 签名图片 |
| 金额相关 | Amount | PrepaidAmount | 预付款 |
| 点数、积分相关 | Point | MemberPoint | 会员积分 |
| 记录相关 | Record | ErrorRecord | 错误记录 |
| 配置相关 | Config | DataBaseConfig | 数据库配置 |
| 状态相关 | Status | OrderStatus | 订单状态 |
| 模式、方式相关 | Mode | OpenMode | 打开方式 |
| 种类相关 | Category / Type(类型) / Class 三选一 | UserCategory | 用户种类 |
| 工厂类相关 | Factory | ConnectionFactory | 连接工厂 |
| 启用相关 | Enabled | ExportEnabled | 开启导出 |
| 流相关 | Stream | UploadStream | 上传流 |
| 读取器相关 | Reader | ExcelReader | Excel读取器 |
| 写入器相关 | Writer | ExcelWriter | Excel写入器 |
| 适配器相关 | Adapter | IntroOPAdapter | IntroOP适配器 |
| 提供器相关 | Provider | MemebershipProvider | 会员信息提供器 |
| 包装器相关 | Wrapper | ProductWrapper | Product包装器 |
| 连接相关 | Connection | ExcelConnection | Excel连接 |
4、常见类型命名
凡存在下表中的类型，需采用下表指定的名称命名。
| 命名 | 类型 | 命名 | |
| 客户 | Customer | 分销商 | Reseller |
| 零售商 | Retailer | 经销商/批发商 | Dealer |
| 用户 | user | 订单 | Order |
| 供应商 | Supplier | 管理员 | Admin |
| 密码 | Password | 会员 | Member |
| 评论 | Remark | 文章 | Article |
| 新闻 | News | 发票 | Invoice |
| 导入 | Import | 导出 | Export |
| 公司、企业 | Company | 产品 | Product |
| 省份 | Province | 城市 | City |
| 区县 | District | 地址 | Address |
| 角色 | Role | 权限 | Authority |
| 仓库 | Warehouse | 工厂 | Plant |
| 登录 | Login | 登出 | LogOut |
| 创建 | Create | 编辑 | Edit |
| 更新 | Update | 删除 | Remove |
| 照片 | Photo | 图片 | Image |
5、 常见字段，属性命名
字段、属性种类比较繁杂，因此仅列出最常用的几项。
| 名称 | 类型 | 名称 | |
| Id（int型） | Id（“d”小写，弃用ID） | GuidId（Guid型） | Id |
| Name | 名称 | Title | 标题 |
| Remark | 备注、描述（弃用Memo、Description） | Category | 种类（弃用Class、Type） |
上面的一些命名引用了张子阳等一些人的文档，以后再慢慢补充丰富起来。不早了，今晚得睡觉了。
