C#注释规范
来源:互联网 发布:芬兰 网络 编辑:程序博客网 时间:2024/06/05 14:54
5. 注释
5.1. 注释的基本约定
注释应该增加代码的清晰度;
保持注释的简洁,不是任何代码都需要注释的,过多的注释反而会影响代码的可读性。
注释不要包括其他的特殊字符。
建议先写注释,后写代码,注释和代码一起完成
如果语句块(比如循环和条件分枝的代码块)代码太长,嵌套太多,则在其结束“}”要加上注释,标志对应的开始语句。如果分支条件逻辑比较复杂,也要加上注释。
在VS2005环境中通过配置工程编译时输出XML文档文件可以检查注释的完整情况,如果注释不完整会报告编译警告;
5.2. 注释类型
5.2.1. 块注释
主要用来描述文件,类,方法,算法等,放在所描述对象的前边。具体格式以IDE编辑器输入“///”自动生成的格式为准,另外再附加我们自定义的格式,如下所列:
/// <Remark>作者,创建日期,修改日期</Remark >
对类和接口的注释必须加上上述标记,对方法可以视情况考虑
5.2.2. 行注释
主要用在方法内部,对代码,变量,流程等进行说明。整个注释占据一行。
5.2.3. 尾随注释
与行注释功能相似,放在代码的同行,但是要与代码之间有足够的空间,便于分清。例:
int m = 4 ; // 注释
如果一个程序块内有多个尾随注释,每个注释的缩进要保持一致。
5.3. 注释哪些部分
项目
注释哪些部分
参数
参数用来做什么
任何约束或前提条件
字段/属性
字段描述
类
类的目的
已知的问题
类的开发/维护历史
接口
目的
它应如何被使用以及如何不被使用
局部变量
用处/目的
成员函数注释
成员函数做什么以及它为什么做这个
哪些参数必须传递给一个成员函数
成员函数返回什么
已知的问题
任何由某个成员函数抛出的异常
成员函数是如何改变对象的
包含任何修改代码的历史
如何在适当情况下调用成员函数的例子适用的前提条件和后置条件
成员函数内部注释
控制结构
代码做了些什么以及为什么这样做
局部变量
难或复杂的代码
处理顺序
5.4. 程序修改注释
新增代码行的前后要有注释行说明,对具体格式不作要求,但必须包含作者,新增时间,新增目的。在新增代码的最后必须加上结束标志;
删除代码行的前后要用注释行说明,删除代码用注释原有代码的方法。注释方法和内容同新增;删除的代码行建议用#region XXX #endregion 代码段折叠,保持代码文件干净整洁
修改代码行建议以删除代码行后再新增代码行的方式进行(针对别人的代码进行修改时,必须标明,对于自己的代码进行修改时,酌情进行)。注释方法和内容同新增;
- C#文档注释规范
- C# 代码注释规范
- C# 代码注释规范
- C#文档注释规范
- C#文档注释规范
- C#注释规范
- C# 注释规范
- c#注释规范
- c# 注释规范
- c#的注释规范
- C# 文档注释规范
- C# 文档注释规范
- C#文档注释规范示例
- C# 注释(Comment)规范
- C# 编程规范 第三章 程序注释
- C#代码注释规范及文档生成
- 注释规范
- 注释规范
- C#命名规范
- 学习笔记:ORACLE 性能优化求生指南
- 中国软件开发需要注意的地方
- 使用bochs调试操作系统
- TI 海思 安霸...摄像机芯片简要介绍
- C#注释规范
- QRegExp
- 软件随想录:程序员部落酋长Joel谈软件(local.joelonsoftware.com/wiki)-10
- SharedPreferences 简单使用
- Android学习笔记之EditText限制输入
- 看完后认真想10秒钟,你会改变自己....................
- android界面——项目结构
- 放弃是一种智慧,分享是一种美德
- ExtJS数据存储与传输