来给regular组件写注释吧

在基本完全组件化的前端工程中，调用组件就像调用函数一样常见：

调用函数时，我们传入参数，得到计算结果；
调用组件时，我们传入数据，得到渲染视图；

不同的是，函数的参数通常只有1-5个左右，清晰的罗列在函数的定义过程中，而组件的数据，常常多达数十个，掺杂在html视图和js的逻辑中。

在这种情况下，调用某个组件的时候，工作过程是这样的：

组件作者提供了示例代码：
- 从示例中找到引用组件的代码，得到需要传给组件的数据
- 如果数据是对象结构，从js中梳理出对象的属性
组件作者没有提供示例代码：）
- 从html中找到所有视图数据
- 从js中梳理出视图数据的来龙去脉，得到传入的数据

梳理过程的复杂度和组件的复杂度呈现正相关，难度和组件涉及的业务难度呈现正相关。总的来说，梳理是最耗时、最折磨人的。

怎样才能提高梳理过程的效率呢？

想起曾经有同事调用我的组件的时候，提出了给组件写示例代码的要求，现在想起来，他应该也饱受梳理的折磨。现在的我，经历了一番题库的折磨后，恍然大悟：

注释，就能有效的提高梳理效率。但是，年轻的少年猿啊，你真的会写注释吗？

写注释，本质上是一件比Hello，World更简单的事情（斜杠+*号，谁还不会呢

关于注释，

有人信奉注释越少越好，命名良好的变量就是天然的最佳注释。
有些人很喜欢写注释，一个文件中的注释足以构成一道阅读理解题。

而有些人从不写注释：

对于函数而言，通常能做到职责单一，职责单一保证了参数较少，配合命名良好的变量，确实能做到不需要注释，下面的函数，基本上一看就能知道它的功能以及调用方法。

arabicToChineseFilter = function (arabicNumber) {
    var BIG_QUESTION_ORDER_NUMBER = ['', '一', '二', '三', '四', '五', '六', '七', '八', '九'],
    UNIT = ['', '千', '百', '十', ''],

    chineseNumber = String(arabicNumber)
        .split("")
        .reduceRight(function (pre, cur, idx) {
            return (cur ? BIG_QUESTION_ORDER_NUMBER[Number(cur)] + UNIT[idx] : '') + pre;
        }, '');

    return chineseNumber;
};

所以，函数的注释相对少见，也并不影响使用，但组件：

所需数据能够多达数十个
在组件的声明处，通常不会有所需参数的定义，即使有，也不清晰（regular对此没有约束）

不过，函数的注释标准，借鉴到组件中来，效果却是很不错：

/**
 * knowledge组件
 * 
 * @param {Object} resource
 * @param {String} [resource.comment=''] 自定义评论
 * 
 * @param {Object[]} knowledgeLogicPoints 题目关联知识点
 * @param {String} knowledgeLogicPoints[].name 知识点的名称
 * 
 * @param {Object[]} [microCourseVideo=[]] 本次答题关联的微课视频
 * @param {String} microCourseVideo[].name 微课视频的名称
 * @param {Number} microCourseVideo[].id 微课视频的id
 */

从上面的注释中，可以立刻得到组件所需的数据结构：

setting: {
  isDisabled
}
question: {
   questionSocore:
   subjectiveQuestionContent: {
        stdAnswer: []
  }
}

注释的标准格式文档

来给regular组件写注释吧

推荐阅读更多精彩内容