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

3、常见后缀命名

凡符合下表所列的局部变量、方法参数、字段、属性，均需添加相应的后缀。

后缀	示例	示例说明
费用相关	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）

上面的一些命名引用了张子阳等一些人的文档，以后再慢慢补充丰富起来。不早了，今晚得睡觉了。