Caos

30 Dec 2017

谈谈 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

 
Caos at 2017-12-30

scribble