通用约定

    注释

    • As short as possible（如无必要，勿增注释）：尽量提高代码本身的清晰性、可读性。
    • As long as necessary（如有必要，尽量详尽）：合理的注释、空行排版等，可以让代码更易阅读、更具美感。

    单行注释

    必须独占一行。 后跟一个空格，缩进与下一行被注释说明的代码一致。

    多行注释

    避免使用 /*...*/ 这样的多行注释。有多行注释内容时，使用多个单行注释。

    函数/方法注释

    1. 函数/方法注释必须包含函数说明，有参数和返回值时必须使用注释标识。；
    2. 参数和返回值注释必须包含类型信息和说明；
    3. 当函数是内部函数，外部不可访问时，可以使用 @inner 标识；

    文件注释

    文件注释用于告诉不熟悉这段代码的读者这个文件中包含哪些东西。 应该提供文件的大体内容, 它的作者, 依赖关系和兼容性信息。如下:

    1. /**
    2.  * @fileoverview Description of file, its uses and information
    3.  * about its dependencies.
    4.  * @author user@meizu.com (Firstname Lastname)
    5.  * Copyright 2009 Meizu Inc. All Rights Reserved.
    6.  */

    命名

    1. var loadingModules = {};

    私有属性、变量和方法以下划线 _ 开头。

    1. var _privateMethod = {};

    常量, 使用全部字母大写，单词间下划线分隔的命名方式。

    1. var HTML_ENTITY = {};
    1. 函数, 使用 Camel 命名法。
    2. 函数的参数, 使用 Camel 命名法。
    1. function stringFormat(source) {}
    3. function hear(theBells) {}
    1. 类, 使用 Pascal 命名法
    2. 类的 方法 / 属性, 使用 Camel 命名法
    1. 枚举变量 使用 Pascal 命名法。
    2. 枚举的属性， 使用全部字母大写，单词间下划线分隔的命名方式。
    1. var TargetState = {
    2.     READING: 1,
    3.     READED: 2,
    4.     APPLIED: 3,
    5.     READY: 4
    6. };

    由多个单词组成的 缩写词，在命名中，根据当前命名法和出现的位置，所有字母的大小写与首字母的大小写保持一致。

    1. function XMLParser() {}
    3. function insertHTML(element, html) {}
    5. var httpRequest = new HTTPRequest();

    命名语法

    类名，使用名词。

    1. function Engine(options) {}

    函数名，使用动宾短语。

      boolean 类型的变量使用 is 或 has 开头。

      1. var isReady = false;
      2. var hasMoreCommands = false;

      Promise 对象用动宾短语的进行时表达。

      接口命名规范

      1. 可读性强，见名晓义；
      2. 尽量不与 jQuery 社区已有的习惯冲突；
      3. 尽量写全。不用缩写，除非是下面列表中约定的；（变量以表达清楚为目标，uglify 会完成压缩体积工作）

      True 和 False 布尔表达式

      下面的布尔表达式都返回 false:

      • null
      • undefined
      • ‘’ 空字符串
      • 0 数字0

      但小心下面的, 可都返回 true:

      • ‘0’ 字符串0
      • [] 空数组
      • {} 空对象

      不要在 Array 上使用 for-in 循环

      for-in 循环只用于 object/map/hash 的遍历, 对 Array 用 for-in 循环有时会出错. 因为它并不是从 0 到 length - 1 进行遍历, 而是所有出现在对象及其原型链的键值。

      1. // Not recommended
      2. function printArray(arr) {
      3.   for (var key in arr) {
      4.     print(arr[key]);
      5.   }
      6. }
      8. printArray([0,1,2,3]);  // This works.
      10. var a = new Array(10);
      11. printArray(a);  // This is wrong.
      13. a = document.getElementsByTagName('*');
      14. printArray(a);  // This is wrong.
      16. a = [0,1,2,3];
      17. a.buhu = 'wine';
      18. printArray(a);  // This is wrong again.
      20. a = new Array;
      21. a[3] = 3;
      22. printArray(a);  // This is wrong again.
      24. // Recommended
      25. function printArray(arr) {
      26.   var l = arr.length;
      27.   for (var i = 0; i < l; i++) {
      28.     print(arr[i]);
      29.   }
      30. }

      二元和三元操作符

      操作符始终写在前一行, 以免分号的隐式插入产生预想不到的问题。

      1. var x = a ? b : c;
      3.     longButSimpleOperandB : longButSimpleOperandC;
      5. var z = a ?
      6.         moreComplicatedB :
      7.         moreComplicatedC;

      . 操作符也是如此：

      1. var x = foo.bar().
      2.     doSomething().
      3.     doSomethingElse();

      条件(三元)操作符 (?:)

      三元操作符用于替代 if 条件判断语句。

      1. // Not recommended
      3.   return foo();
      4. } else {
      5.   return bar();
      6. }
      8. // Recommended
      9. return val ? foo() : bar();

      && 和 ||

      二元布尔操作符是可短路的, 只有在必要时才会计算到最后一项。

      1. // Not recommended
      2. function foo(opt_win) {
      3.   var win;
      4.   if (opt_win) {
      5.     win = opt_win;
      6.   } else {
      7.     win = window;
      8.   }
      9.   // ...
      10. }
      12. if (node) {
      13.   if (node.kids) {
      14.     if (node.kids[index]) {
      15.       foo(node.kids[index]);
      16.     }
      17.   }
      18. }
      20. // Recommended
      21. function foo(opt_win) {
      22.   var win = opt_win || window;
      23.   // ...
      24. }
      26. var kid = node && node.kids && node.kids[index];
      27. if (kid) {
      28. }