谈谈 JavaScript 中的注释

代码注释对长久维护的项目来说很重要，随着前端代码逻辑日趋复杂，合理的文档注释能提高维护开发效率。尤其在多人团队中，良好的注释能降低沟通成本。不过也有观点认为，良好的代码不需要注释，因为其本身就能自描述，比如良好的命名和代码结构等等。

一个程序员的代码只有他自己和上帝看得懂，过了几个月，只有上帝能看得懂了。

实际开发过程中，业务场景复杂，开发者很难做到代码自描述，而且单纯根据阅读代码来了解功能是不够的，代码之中也会因为适配具体业务变得不易读，需要有一定的辅助描述或示例给与说明，开发人员能从注释中大致明白代码做了什么，和为什么这么做。

注释规范

注释应当有规范，不管是 Javadoc、 phpDocumentor、还是 JsDoc 都遵循了一定的规范，让注释统一格式，再通过扫描文档中的注释生成可视化文档。以上三者都使用了相似的注释标签，形成了默契的标准。这样的好处是，即便是不同语言的使用者，也能够通过注释了解代码结构从而理解需求。

另外注释生成工具之间的切换也能达到无缝衔接，例如我在开发过程中使用了 ES6 和一些 ES7 特性，但注释是按照 JsDoc 的规范编写，项目结束之后生成的文档出现了一些问题，后来发现 JsDoc 对 React Module 式的写法支持不太好，百般调试都达不到想要的结果，无奈要切到 EsDoc ，不过两者标签定义相同，只需要新增配置文件，更换生成工具即可。原有的注释依然可以被 EsDoc 识别，免去了不少麻烦。

注释原则

理想情况下注释要与开发同时进行，例如函数的注释包含参数与返回值，在开发过程中编写，不仅能达到合理覆盖，也降低了注释维护成本。

有时也需要在开发过程中为他人的代码补全注释，如同阅读理解，关键信息点需要有标注或提示帮助记忆，文章和程序都属于思想的载体，程序代码结构关系明显但容易分散，所以需要在阅读过程中添加提示或标注。

注释体现清晰的项目结构与代码结构，可以单单从注释文档理解项目文件结构和设计结构。比如合理的命名空间与前缀，模块描述等等。

注释规约

下文是之前基于 JsDoc 整理的注释规约，稍作修改依然适用于 EsDoc。

函数的注释分为三部分，依次排列
- 函数描述，作为函数主要功能的描述
- 函数如果有参数则添加 @param 注释
  - 参数类型通过 @param {type} arg - desc 详见type 文档
  - 若参数为对象需要标注属性则分开标注 @param {type} arg.attr
  - 参数可选则 @param {type=} arg - desc
  - 有默认值的参数 @param {type=defaltValue}
  - 可能为多种类型的参数 @param {string|object}
  - 回调函数类型的参数 @param {requestCallback} cb - desc 或使用 @callback cb 推荐第一种写法
- 函数返回值 @returns {type}
更新注解之后需要在 task 目录运行 npm run docs 生成新的文档就能看到效果
类 / 模块标注规则 @module scop/name 描述添加在 @desc
- 数据模型则在文件头部使用 @ module models/xxx - {desc} 注释
- 业务组件模块在文件头部使用 @module layout/xxx - {desc} 注释
- 通用组件模块在文件头部使用 @module component/xxx - {desc} 注释
- 工具类文件模块在文件头部使用 @module help/xxx - {desc} 注释
- 模块内部声明的组件类
  - 根据功能在类声明之前添加注释
  - 需添加描述注释 @desc 并添加描述
  - 按照@alias layout/xxx - {name}
  - 不必使用 @module 注释
  - 若不想类显示在 doc 中，则添加 @ignore 注释即可
如果文件中有单独 export 的对象，需要在导出的对象前添加 @exports xxx 来作为 @module 的替代

2017-12-30