☍组件规范

定义组件开发的最高级别规范。

命名

选词

词性

缩写

通用命名

同义词

格式规范

符号

逻辑

文档注释规范

☍命名

☍选词

• 所有公开接口和文档应使用书面语。
• 所有单词按照美式英语发音、拼写。
• 专业术语缩写使用全大写格式，如果在开头则使用全小写格式。如 innerHTML、html。

☍词性

• 函数（方法）名应为动词、动宾结构或介宾结构。如 find、findIndex。
• 变量（参数）、属性名应为名词、形容词或偏正结构。如 location、disabled。
• 类名、ID、CSS 类名应为名词。
• 在表示多个（数组、列表）或可组合的枚举时使用名词的复数形式。如 childNodes。
• 在返回布尔值的方法名中使用动词的第三人称形式。如 hasClass、matches。

☍缩写

• 除了常见缩写和专业术语，所有公开接口（包括参数名）尽量使用单词全拼。

☍通用命名

如果需要定义一个无特定意义的变量（参数），按照以下原则命名：

• 使用 i 作为循环变量。嵌套循环则依次使用 j、k、h...。

❐for (let i = 0; i < 100; i++) {
    for (let j = i; i < 100; j++) {

    }
}

• 在函数中，使用 r 保存需要最终返回的值。

❐function getHtml(){
    let r = "";
    if (...) {
        r += "<a>";
    }
    return r;
}

❐function getItems(){
    const r = [];
    if (...) {
        r.push(1);
    }
    return r;
}

• 使用 t 保存无特定类型的内部变量。

❐function swap(item1, item2){
    var t = item1;
    item1 = item2;
    item2 = t;
}

• 使用 value 保存无特定类型的变量。
• 分别使用以下变量保存对应类型的变量：
  • 使用 obj 保存对象类型的变量。
  • 使用 arr 保存数组类型的变量。
  • 使用 str 保存字符串类型的变量。
  • 使用 fn 保存函数类型的变量。
  • 使用 num 保存数字类型的变量。
  • 使用 date 保存日期类型的变量。
  • 使用 list 保存类数组类型的变量。
  • 使用首字母小写的同名变量保存自定义类型的变量。
• 使用 item 保存数组中的每一项。
• 使用 key 保存对象的键或加密的密钥。
• 使用 count 保存次数。
• 使用 timeout 保存超时的毫秒数。
• 使用 options 保存可组合的选项对象。
• 使用 callback 保存不区分成功和失败的回调函数。使用 success 和 error 分别保存成功和失败回调。
• 使用 x、y、z 保存需要作四则运算的值或坐标值。
• 使用 data 保存外部获取的（一般由服务器下发的）数据。
• 使用 e 保存事件参数。
• 使用 thisArg 保存函数中 this 的值。
• 使用 _this 临时保存原函数的 this。
• 使用 startIndex、endIndex 分别保存开始索引和结束索引。
• 使用 compareFn 保存排序比较函数。

☍同义词

delete & remove

两者都是去除的意思。

• remove 表示暂时性的移除，之后可以通过 add 重新添加。
• delete 表示不可撤销的删除。delete 总是和 create、new 对应。

create & new

两者都是创建的意思。

• create 作动词使用，常用于函数名。
• new 作形容词使用，常用于变量名。

state & status

两者都是状态的意思。

• state 是有限的、可枚举的状态，一般是一个数字。
• status 是不可确定的、可拓展的状态，一般是一个字符串。

start & begin

两者都是开始的意思。

• start 作名词使用，常用于属性名和变量名。
• begin 作动词使用，常用于函数名。

☍格式规范

☍符号

• 中文和英文、数字之间空一格。
• 文档注释句尾应添加句号。英文使用“.”，中文使用“。”。

☍逻辑

• 尽量降低嵌套层次。如 if-return-else 可简写为 if-return：

❐if (...) {
    return ...
}

if (...) {
    return ...
}

return ...

• 尽量将更短的代码放在 if 中，而不是 else 中。

• 如果变量不再重新赋值则使用 const，否则使用 let。仅全局变量使用 var。

☍文档注释规范

• 使用 @desc 代替 @description。
• 使用 @file 代替 @fileOverview。
• 使用 @return 代替 @returns。
• 使用 @throw 代替 @exception。