首页 > 代码库 > 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 或 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) |
上面的一些命名引用了张子阳等一些人的文档,以后再慢慢补充丰富起来。不早了,今晚得睡觉了。
C# 编码标准(三)