0 前言

随着业务的壮大，我们会经常需要重构与优化项目。

在这种重构工作里，有两件事会让人很头疼。

其一是存在很多公用函数、mixin等供项目成员共用的共享单元。面对这种会产生多对多关系(比如一个组件用了多个公用函数、一个公用函数被多个组件使用)的代码结构，无疑让人头疼。

其二是由于各种原因，无法使用typescript。在缺少类型提示的情况下是无法直接让代码文档化的。这样的后果就是日后可能会再次重构该项目，那有极大的可能会把踩过的坑再踩一次。

以上两种情况无疑极大拖慢了开发效率：

一方面是时间都花在搞懂代码功能上了
另一方面主要是花在重复的沟通上。这点尤为致命，一方面是打断了别人的工作，另一方面是浪费了自己的时间，有时候还要等待别人的回复，损耗更大。

在目前的局限性下，只能渐进式地通过清晰地函数注释尽可能减少这种损耗。

ps：如果有机会，一定要使用typescript。

1 JS函数注释规范

1.1 描述函数作用或功能

格式为@description descriptionStatements
专注于what
较为复杂的业务可以适当写why

/**
 * @description 描述fn的作用或功能
 */

1.2 描述参数

格式为@param {paramDataType} p1 descriptionStatements
p1代表必选参数
[p1]代表可选参数
[p1=xxx]代表带默认值的参数

/**
 * @param {string} a 参数描述
 * @param {number} [b] 参数描述
 * @param {boolean} [c=false] 参数描述
 */

1.3 描述为数组的参数

参数为数组必须对其每个元素进行详细描述
元素描述规则参考1.2小节

格式如下

/**
 * 数组参数：
 * @param {array} arr 参数描述
 * @param {string} arr[0] 参数描述
 * @param {number} [arr[1]=undefined] 参数描述
 */

1.4 描述返回值

格式为@return {paramDataType} descriptionStatements
即使无返回值，也要写@return {undefined}

/**
 * @return {number} 描述返回值
 */

1.5 完整例子

完整注释如下

/**
 * @description 描述fn的作用或功能
 * @param {string} a 参数描述
 * @param {number} [b] 参数描述
 * @param {boolean} [c=false] 参数描述
 *
 * 数组参数：
 * @param {array} arr 参数描述
 * @param {string} arr[0] 参数描述
 * @param {number} [arr[1]=undefined] 参数描述
 *
 * @return {number} 描述返回值
 */
function fn(a, b, c = false) {
  // code
  return 1;
}

例子

  /**
   * @description 对树形组件数据进行修正，本地化操作，仅需执行一次
   * @param {object} data 从后端拉取的未修改数据
   * @return {undefined} 无需返回值
   */
  cleanLeftMenuData(data) {
    // ....
  }

2 自动生成文档注释IDE配置

效果如下所示：

动画.gif

2.1 webstorm

打开setting，按下图步骤来把如下注释按照图示拷贝进去

2.2 vscode

vscode建议直接安装插件document this

其配置方法如下图所示

JS函数注释规范及IDE配置