在基本完全组件化的前端工程中，调用组件就像调用函数一样常见：
- 调用函数时，我们传入参数，得到计算结果；
- 调用组件时，我们传入数据，得到渲染视图；
不同的是，函数的参数通常只有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: []
}
}
注释的标准格式文档
网友评论