代码规范-注释

代码规范-注释

引言-《代码大全》

对于投机取巧的代码注释是错误的，注释不应该帮扶难度大的代码，就像kernighan和plauger强调的:”不要注释糟糕的代码—-应重写之。”

很多人支持优质的代码应该是自解释的

在程序员的圈子中，有很多非常优秀的程序员都是不太愿意写注释的，他们往往会认为优质的代码应该是自解释的。在习惯性的不写注释时，他们会更用心地写好变量名，函数名，代码质量会进一步提高。

很多人支持代码中30%+的是注释

大部分代码都需要维护，而维护者往往不是本人，当别人在阅读你大篇幅代码的时候对你的变量或函数命名理解起来可能会存在偏差，对于一些复杂的函数，一个简单的函数名并不能很好的体现其函数功能，复杂的需求往往不易理解，而这个时候通过阅读注释的就能更好的理解代码意图。使代码更易维护。

个人观点

曾经的我也期望写出自解释风格的代码，慢慢的当自己在维护别人代码的时候，合理注释相对较多的代码，往往更易于理解和维护，而那种通篇没有一行注释的代码理解起来的成本更高，而部分复杂的需求更不能简单的通过代码来理解。

统一规范的代码注释风格可以提高团队工作效率

推荐的注释原则

原则：

1、注释形式统一

在整个应用程序中，使用具有一致的标点和结构的样式来构造注释。如果在其它项目中发现它们的注释规范与这份文档不同，按照这份规范写代码，不要试图在既成的规范系统中引入新的规范。

2、注释内容准确简洁

内容要简单、明了、含义准确，防止注释的多义性，错误的注释不但无益反而有害。

注释条件：

1、基本注释（必须加）

(a) 类（接口）的注释

(b) 构造函数的注释

(c) 方法的注释

(d) 全局变量的注释

(e) 字段/属性的注释

备注：简单的代码做简单注释，注释内容不大于10个字即可，另外，持久化对象或VO对象的getter、setter方法不需加注释。具体的注释格式请参考下面举例。

2、特殊必加注释（必须加）

(a) 典型算法必须有注释。

(b) 在代码不明晰处必须有注释。

(c) 在代码修改处加上修改标识的注释。

(d) 在循环和逻辑分支组成的代码中加注释。

(e) 为他人提供的接口必须加详细注释。

常用注释格式举例

• 如果某段代码有功能未实现，或者有待完善，必须添加“TODO”标记，“TODO”前后应留一个空格。例如

// TODO 未处理IE6-8的兼容性
function setOpacity(node, val) {
    node.style.opacity = val;
}

• 文档注释将会以预定格式出现在API文档中。它以“/*”开头，以“/”结束，其间的每一行均以“”开头（均与开始符的第一个“”对齐），且注释内容与“*”间留一个空格。例如：

/**
 * comment
 */

• @module。声明模块，用法：

/**
 * 模块说明
 * @module 模块名
 */

• @method。声明函数或类方法，用法

/**
 * 方法说明
 * @method 方法名
 * @for 所属类名
 * @param {参数类型} 参数名 参数说明
 * @return {返回值类型} 返回值说明
 */

-

http://www.zhihu.com/question/21880307
http://zh-google-styleguide.readthedocs.io/en/latest/google-cpp-styleguide/comments/