首页 > 代码库 > C# 编码标准(三)

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

lv

DataGrid

dg

2 常见集合类型后缀命名

凡符合下表所列的集合类型,应添加相应的后缀。

说明后缀    示例
数组Array 或 sint[] productArray 或 int[] products 
列表List 或 sList<Product> productList 或 List<Product> products 
DataTable/HashTableTableHashTable productTable 
字典Dictionary 或 DicDictionay<string,string> productDictionary 或 Dictionay<string,string> productDic 
DbSet /DataSetSet 或DataSetDbSet<Product> productSet 或 DbSet<Product> productDataSet 
集合Coll 或 s 或 CollectionTableCollection tables 或 TableCollection tableColl 或 TableCollection tableCollection

3、常见后缀命名

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

后缀示例示例说明
费用相关CostShipCost运输费
价格相关PriceProductUnitPrice产品单价
消息相关MessageSuccessMessage成功消息
日期相关DateOrderDate下单日期
计数、数量相关CountLoginCount登录次数
链接地址相关UrlBlogUrl博客链接
图片相关ImageSignImage签名图片
金额相关AmountPrepaidAmount预付款
点数、积分相关PointMemberPoint会员积分
记录相关RecordErrorRecord错误记录
配置相关ConfigDataBaseConfig数据库配置
状态相关StatusOrderStatus订单状态
模式、方式相关ModeOpenMode打开方式
种类相关Category / Type(类型) / Class 三选一UserCategory用户种类
工厂类相关FactoryConnectionFactory连接工厂
启用相关EnabledExportEnabled开启导出
流相关StreamUploadStream上传流
读取器相关ReaderExcelReaderExcel读取器
写入器相关WriterExcelWriterExcel写入器
适配器相关AdapterIntroOPAdapterIntroOP适配器
提供器相关ProviderMemebershipProvider会员信息提供器
包装器相关WrapperProductWrapperProduct包装器
连接相关ConnectionExcelConnectionExcel连接

 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)

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

C# 编码标准(三)