摘要：強制參數和返回值注釋必須包含類型信息和說明。如果重寫的形參個數類型順序和返回值類型均未發生變化，可省略，僅用標識，否則仍應作完整注釋。

轉載：原地址

JavaScript在百度一直有著廣泛的應用，特別是在瀏覽器端的行為管理。本文檔的目標是使JavaScript代碼風格保持一致，容易被理解和被維護。

雖然本文檔是針對JavaScript設計的，但是在使用各種JavaScript的預編譯語言時(如TypeScript等)時，適用的部分也應盡量遵循本文檔的約定。

[建議] JavaScript 文件使用無 BOM 的 UTF-8 編碼。

解釋：

UTF-8 編碼具有更廣泛的適應性。BOM 在使用程序或工具處理文件時可能造成不必要的干擾。

[建議] 在文件結尾處，保留一個空行。

[強制] 使用 4 個空格做為一個縮進層級，不允許使用 2 個空格 或 tab 字符。

[強制] switch 下的 case 和 default 必須增加一個縮進層級。

示例：

javascript// good
switch (variable) {

    case "1":
        // do...
        break;

    case "2":
        // do...
        break;

    default:
        // do...

}

// bad
switch (variable) {

case "1":
    // do...
    break;

case "2":
    // do...
    break;

default:
    // do...

}

javascriptvar a = !arr.length;
a++;
a = b + c;

javascript// good
if (condition) {
}

while (condition) {
}

function funcName() {
}

// bad
if (condition){
}

while (condition){
}

function funcName(){
}

javascript// good
if (condition) {
}

while (condition) {
}

(function () {
})();

// bad
if(condition) {
}

while(condition) {
}

(function() {
})();

javascript// good
var obj = {
    a: 1,
    b: 2,
    c: 3
};

// bad
var obj = {
    a : 1,
    b:2,
    c :3
};

javascript// good
function funcName() {
}

var funcName = function funcName() {
};

funcName();

// bad
function funcName () {
}

var funcName = function funcName () {
};

funcName ();

javascript// good
callFunc(a, b);

// bad
callFunc(a , b) ;

javascript// good

callFunc(param1, param2, param3);

save(this.list[this.indexes[i]]);

needIncream && (variable += increament);

if (num > list.length) {
}

while (len--) {
}


// bad

callFunc( param1, param2, param3 );

save( this.list[ this.indexes[ i ] ] );

needIncreament && ( variable += increament );

if ( num > list.length ) {
}

while ( len-- ) {
}

javascript// good
var arr1 = [];
var arr2 = [1, 2, 3];
var obj1 = {};
var obj2 = {name: "obj"};
var obj3 = {
    name: "obj",
    age: 20,
    sex: 1
};

// bad
var arr1 = [ ];
var arr2 = [ 1, 2, 3 ];
var obj1 = { };
var obj2 = { name: "obj" };
var obj3 = {name: "obj", age: 20, sex: 1};

javascript// good
if (user.isAuthenticated()
    && user.isInRole("admin")
    && user.hasAuthority("add-admin")
    || user.hasAuthority("delete-admin")
) {
    // Code
}

var result = number1 + number2 + number3
    + number4 + number5;


// bad
if (user.isAuthenticated() &&
    user.isInRole("admin") &&
    user.hasAuthority("add-admin") ||
    user.hasAuthority("delete-admin")) {
    // Code
}

var result = number1 + number2 + number3 +
    number4 + number5;

javascript// good
var obj = {
    a: 1,
    b: 2,
    c: 3
};

foo(
    aVeryVeryLongArgument,
    anotherVeryLongArgument,
    callback
);


// bad
var obj = {
    a: 1
    , b: 2
    , c: 3
};

foo(
    aVeryVeryLongArgument
    , anotherVeryLongArgument
    , callback
);

javascript// 僅為按邏輯換行的示例，不代表setStyle的最優實現
function setStyle(element, property, value) {
    if (element == null) {
        return;
    }

    element.style[property] = value;
}

javascript// 較復雜的邏輯條件組合，將每個條件獨立一行，邏輯運算符放置在行首進行分隔，或將部分邏輯按邏輯組合進行分隔。
// 建議最終將右括號 ) 與左大括號 { 放在獨立一行，保證與 if 內語句塊能容易視覺辨識。
if (user.isAuthenticated()
    && user.isInRole("admin")
    && user.hasAuthority("add-admin")
    || user.hasAuthority("delete-admin")
) {
    // Code
}

// 按一定長度截斷字符串，并使用 + 運算符進行連接。
// 分隔字符串盡量按語義進行，如不要在一個完整的名詞中間斷開。
// 特別的，對于HTML片段的拼接，通過縮進，保持和HTML相同的結構。
var html = "" // 此處用一個空字符串，以便整個HTML片段都在新行嚴格對齊
    + "
"
    +     "

Title here

"
    +     "

This is a paragraph

"
    +     ""
    + "
";

// 也可使用數組來進行拼接，相對 + 更容易調整縮進。
var html = [
    "
",
        "

Title here

",
        "

This is a paragraph

",
        "",
    "
"
];
html = html.join("");

// 當參數過多時，將每個參數獨立寫在一行上，并將結束的右括號 ) 獨立一行。
// 所有參數必須增加一個縮進。
foo(
    aVeryVeryLongArgument,
    anotherVeryLongArgument,
    callback
);

// 也可以按邏輯對參數進行組合。
// 最經典的是baidu.format函數，調用時將參數分為“模板”和“數據”兩塊
baidu.format(
    dateFormatTemplate,
    year, month, date, hour, minute, second
);

// 當函數調用時，如果有一個或以上參數跨越多行，應當每一個參數獨立一行。
// 這通常出現在匿名函數或者對象初始化等作為參數時，如setTimeout函數等。
setTimeout(
    function () {
        alert("hello");
    },
    200
);

order.data.read(
    "id=" + me.model.id, 
    function (data) {
        me.attchToModel(data.result);
        callback();
    }, 
    300
);

// 鏈式調用較長時采用縮進進行調整。
$("#items")
    .find(".selected")
    .highlight()
    .end();

// 三元運算符由3部分組成，因此其換行應當根據每個部分的長度不同，形成不同的情況。
var result = thisIsAVeryVeryLongCondition
    ? resultA : resultB;

var result = condition
    ? thisIsAVeryVeryLongResult
    : resultB;

// 數組和對象初始化的混用，嚴格按照每個對象的 { 和結束 } 在獨立一行的風格書寫。
var array = [
    {
        // ...
    },
    {
        // ...
    }
];

javascriptif (condition) {
    // some statements;
}
else {
    // some statements;
}

try {
    // some statements;
}
catch (ex) {
    // some statements;
}

javascript// good
if (condition) {
    callFunc();
}

// bad
if (condition) callFunc();
if (condition)
    callFunc();

javascript// good
function funcName() {
}

// bad
function funcName() {
};

// 如果是函數表達式，分號是不允許省略的。
var funcName = function () {
};

javascript// good
var task = (function () {
   // Code
   return result;
})();

var func = function () {
};


// bad
var task = function () {
    // Code
    return result;
}();

var func = (function () {
});

javascriptvar loadingModules = {};

javascriptvar HTML_ENTITY = {};

javascriptfunction stringFormat(source) {
}

javascriptfunction hear(theBells) {
}

javascriptfunction TextNode(options) {
}

javascriptfunction TextNode(value, engine) {
    this.value = value;
    this.engine = engine;
}

TextNode.prototype.clone = function () {
    return this;
};

javascriptvar TargetState = {
    READING: 1,
    READED: 2,
    APPLIED: 3,
    READY: 4
};

javascriptequipments.heavyWeapons = {};

javascriptfunction XMLParser() {
}

function insertHTML(element, html) {
}

var httpRequest = new HTTPRequest();

javascriptfunction Engine(options) {
}

javascriptfunction getStyle(element) {
}

javascriptvar isReady = false;
var hasMoreCommands = false;

javascriptvar loadingData = ajax.get("url");
loadingData.then(callback);

javascript/**
 * @file Describe the file
 */

javascript/**
 * @file Describe the file
 * @author author-name(mail-name@domain.com)
 *         author-name2(mail-name2@domain.com)
 */

javascript/**
 * @namespace
 */
var util = {};

javascript/**
 * 描述
 *
 * @class
 */
function Developer() {
    // constructor body
}

javascript/**
 * 描述
 *
 * @class
 * @extends Developer
 */
function Fronteer() {
    Developer.call(this);
    // constructor body
}
util.inherits(Fronteer, Developer);

javascript/**
 * 類描述
 *
 * @class
 * @extends Developer
 */
function Fronteer() {
    Developer.call(this);
    // constructor body
}

util.extend(
    Fronteer.prototype,
    /** @lends Fronteer.prototype */{
        _getLevel: function () {
            // TODO
        }
    }
);

javascript/**
 * 類描述
 *
 * @class
 * @extends Developer
 */
var Fronteer = function () {
    Developer.call(this);

    /**
     * 屬性描述
     *
     * @type {string}
     * @private
     */
    this._level = "T12";

    // constructor body
};
util.inherits(Fronteer, Developer);

/**
 * 方法描述
 *
 * @private
 * @return {string} 返回值描述
 */
Fronteer.prototype._getLevel = function () {
};

javascript/**
 * 函數描述
 *
 * @param {string} p1 參數1的說明
 * @param {string} p2 參數2的說明，比較長
 *     那就換行了.
 * @param {number=} p3 參數3的說明（可選）
 * @return {Object} 返回值描述
 */
function foo(p1, p2, p3) {
    var p3 = p3 || 10;
    return {
        p1: p1,
        p2: p2,
        p3: p3
    };
}

javascript/**
 * 函數描述
 *
 * @param {Object} option 參數描述
 * @param {string} option.url option項描述
 * @param {string=} option.method option項描述，可選參數
 */
function foo(option) {
    // TODO
}

javascript/**
 * 值變更時觸發
 *
 * @event
 * @param {Object} e e描述
 * @param {string} e.before before描述
 * @param {string} e.after after描述
 */
onchange: function (e) {
}

javascript/**
 * 點擊處理
 *
 * @fires Select#change
 * @private
 */
Select.prototype.clickHandler = function () {
    /**
     * 值變更時觸發
     *
     * @event Select#change
     * @param {Object} e e描述
     * @param {string} e.before before描述
     * @param {string} e.after after描述
     */
    this.fire(
        "change",
        {
            before: "foo",
            after: "bar"
        }
    );
};

javascript/**
 * 常量說明
 *
 * @const
 * @type {string}
 */
var REQUEST_URL = "myurl.do";

javascript// `namespaceA~` 可以換成其它 namepaths 前綴，目的是為了生成文檔中能顯示 `@typedef` 定義的類型和鏈接。
/**
 * 服務器
 *
 * @typedef {Object} namespaceA~Server
 * @property {string} host 主機
 * @property {number} port 端口
 */

/**
 * 服務器列表
 *
 * @type {Array.}
 */
var servers = [
    {
        host: "1.2.3.4",
        port: 8080
    },
    {
        host: "1.2.3.5",
        port: 8081
    }
];

javascriptdefine(
    function (require) {

        /**
         * foo description
         *
         * @exports Foo
         */
        var foo = {
            // TODO
        };

        /**
         * baz description
         *
         * @return {boolean} return description
         */
        foo.baz = function () {
            // TODO
        };

        return foo;

    }
);

javascriptdefine(
    function (require) {

        /**
         * module description.
         *
         * @module foo
         */
        var exports = {};


        /**
         * bar description
         *
         */
        exports.bar = function () {
            // TODO
        };

        return exports;
    }
);

javascript/**
 * module description.
 *
 * @module
 */
define(
    function (require, exports) {

        /**
         * bar description
         *
         */
        exports.bar = function () {
            // TODO
        };
        return exports;
    }
);

javascript/**
 * 點擊處理
 *
 * @fires module:Select#change
 * @private
 */
Select.prototype.clickHandler = function () {
    /**
     * 值變更時觸發
     *
     * @event module:Select#change
     * @param {Object} e e描述
     * @param {string} e.before before描述
     * @param {string} e.after after描述
     */
    this.fire(
        "change",
        {
            before: "foo",
            after: "bar"
        }
    );
};

javascript/**
 * A module representing a jacket.
 * @module jacket
 */
define(
    function () {

        /**
         * @class
         * @alias module:jacket
         */
        var Jacket = function () {
        };

        return Jacket;
    }
);

javascript// one module
define("html/utils",
    /**
     * Utility functions to ease working with DOM elements.
     * @exports html/utils
     */
    function () {
        var exports = {
        };

        return exports;
    }
);

// another module
define("tag",
    /** @exports tag */
    function () {
        var exports = {
        };

        return exports;
    }
);

javascript
// 只使用 @class Bar 時，類方法和屬性都必須增加 @name Bar#methodName 來標識，與 @exports 配合可以免除這一麻煩，并且在引用時可以省去 module: 前綴。
// 另外需要注意類名需要使用 var 定義的方式。

/**
 * Bar description
 *
 * @see foo
 * @exports  Bar
 * @class
 */
var Bar = function () {
    // TODO
};

/**
 * baz description
 *
 * @return {(string|Array)} return description
 */
Bar.prototype.baz = function () {
    // TODO
};

javascriptfunction foo(p1, p2) {
    // 這里對具體內部邏輯進行說明
    // 說明太長需要換行
    for (...) {
        ....
    }
}

javascript// good
var name = "MyName";

// bad
name = "MyName";

javascript// good
var hangModules = [];
var missModules = [];
var visited = {};

// bad
var hangModules = [],
    missModules = [],
    visited = {};

javascript// good
function kv2List(source) {
    var list = [];

    for (var key in source) {
        if (source.hasOwnProperty(key)) {
            var item = {
                k: key,
                v: source[key]
            };
            list.push(item);
        }
    }

    return list;
}

// bad
function kv2List(source) {
    var list = [];
    var key;
    var item;

    for (key in source) {
        if (source.hasOwnProperty(key)) {
            item = {
                k: key,
                v: source[key]
            };
            list.push(item);
        }
    }

    return list;
}

javascript// good
if (age === 30) {
    // ......
}

// bad
if (age == 30) {
    // ......
}

javascript// 字符串為空

// good
if (!name) {
    // ......
}

// bad
if (name === "") {
    // ......
}

javascript// 字符串非空

// good
if (name) {
    // ......
}

// bad
if (name !== "") {
    // ......
}

javascript// 數組非空

// good
if (collection.length) {
    // ......
}

// bad
if (collection.length > 0) {
    // ......
}

javascript// 布爾不成立

// good
if (!notTrue) {
    // ......
}

// bad
if (notTrue === false) {
    // ......
}

javascript// null 或 undefined

// good
if (noValue == null) {
  // ......
}

// bad
if (noValue === null || typeof noValue === "undefined") {
  // ......
}

javascript// good
switch (typeof variable) {
    case "object":
        // ......
        break;
    case "number":
    case "boolean":
    case "string":
        // ......
        break;
}

// bad
var type = typeof variable;
if (type === "object") {
    // ......
} 
else if (type === "number" || type === "boolean" || type === "string") {
    // ......
}

javascript// good
function getName() {
    if (name) {
        return name;
    }

    return "unnamed";
}

// bad
function getName() {
    if (name) {
        return name;
    }
    else {
        return "unnamed";
    }
}

javascript// good
function clicker() {
    // ......
}

for (var i = 0, len = elements.length; i < len; i++) {
    var element = elements[i];
    addListener(element, "click", clicker);
}


// bad
for (var i = 0, len = elements.length; i < len; i++) {
    var element = elements[i];
    addListener(element, "click", function () {});
}

javascript// good
var width = wrap.offsetWidth + "px";
for (var i = 0, len = elements.length; i < len; i++) {
    var element = elements[i];
    element.style.width = width;
    // ......
}


// bad
for (var i = 0, len = elements.length; i < len; i++) {
    var element = elements[i];
    element.style.width = wrap.offsetWidth + "px";
    // ......
}

javascriptfor (var i = 0, len = elements.length; i < len; i++) {
    var element = elements[i];
    // ......
}

javascriptvar len = elements.length;
while (len--) {
    var element = elements[len];
    // ......
}

javascript// string
typeof variable === "string"

// number
typeof variable === "number"

// boolean
typeof variable === "boolean"

// Function
typeof variable === "function"

// Object
typeof variable === "object"

// RegExp
variable instanceof RegExp

// Array
variable instanceof Array

// null
variable === null

// null or undefined
variable == null

// undefined
typeof variable === "undefined"

javascript// good
num + "";

// bad
new String(num);
num.toString();
String(num);

javascript// good
+str;

// bad
Number(str);

javascriptvar width = "200px";
parseInt(width, 10);

javascript// good
parseInt(str, 10);

// bad
parseInt(str);

javascriptvar num = 3.14;
!!num;

javascript// good
var num = 3.14;
Math.ceil(num);

// bad
var num = 3.14;
parseInt(num, 10);

javascriptvar str = "我是一個字符串";
var html = "
拼接HTML可以省去雙引號轉義
";

javascript// 使用數組拼接字符串
var str = [
    // 推薦換行開始并縮進開始第一個字符串, 對齊代碼, 方便閱讀.
    "

",
        "
第一項
",
        "
第二項
",
    "

"
].join("");

// 使用 + 拼接字符串
var str2 = "" // 建議第一個為空字符串, 第二個換行開始并縮進開始, 對齊代碼, 方便閱讀
    + "

",
    +    "
第一項
",
    +    "
第二項
",
    + "

";

javascript// good
var obj = {};

// bad
var obj = new Object();

javascriptvar info = {
    name: "someone",
    age: 28
};

javascript// good
var info = {
    "name": "someone",
    "age": 28,
    "more-info": "..."
};

// bad
var info = {
    name: "someone",
    age: 28,
    "more-info": "..."
};

javascript// 以下行為絕對禁止
String.prototype.trim = function () {
};

javascriptinfo.age;
info["more-info"];

javascriptvar newInfo = {};
for (var key in info) {
    if (info.hasOwnProperty(key)) {
        newInfo[key] = info[key];
    }
}

javascript// good
var arr = [];

// bad
var arr = new Array();

javascriptvar arr = ["a", "b", "c"];
arr.other = "other things"; // 這里僅作演示, 實際中應使用Object類型

// 正確的遍歷方式
for (var i = 0, len = arr.length; i < len; i++) {
    console.log(i);
}

// 錯誤的遍歷方式
for (i in arr) {
    console.log(i);
}

javascriptfunction syncViewStateOnUserAction() {
    if (x.checked) {
        y.checked = true;
        z.value = "";
    }
    else {
        y.checked = false;
    }

    if (!a.value) {
        warning.innerText = "Please enter it";
        submitButton.disabled = true;
    }
    else {
        warning.innerText = "";
        submitButton.disabled = false;
    }
}

// 直接閱讀該函數會難以明確其主線邏輯，因此下方是一種更合理的表達方式：

function syncViewStateOnUserAction() {
    syncXStateToView();
    checkAAvailability();
}

function syncXStateToView() {
    if (x.checked) {
        y.checked = true;
        z.value = "";
    }
    else {
        y.checked = false;
    }
}

function checkAAvailability() {
    if (!a.value) {
        displayWarningForAMissing();
    }
    else {
        clearWarnignForA();
    }
}

javascript/**
 * 移除某個元素
 *
 * @param {Node} element 需要移除的元素
 * @param {boolean} removeEventListeners 是否同時將所有注冊在元素上的事件移除
 */
function removeElement(element, removeEventListeners) {
    element.parent.removeChild(element);
    if (removeEventListeners) {
        element.clearEventListeners();
    }
}

javascript/**
 * 移除某個元素
 *
 * @param {Node} element 需要移除的元素
 * @param {Object} options 相關的邏輯配置
 * @param {boolean} options.removeEventListeners 是否同時將所有注冊在元素上的事件移除
 */
function removeElement(element, options) {
    element.parent.removeChild(element);
    if (options.removeEventListeners) {
        element.clearEventListeners();
    }
}

javascriptvar tasks = [];
for (var i = 0; i < 5; i++) {
    tasks[tasks.length] = function () {
        console.log("Current cursor is at " + i);
    };
}

var len = tasks.length;
while (len--) {
    tasks[len]();
}

javascriptvar tasks = [];
for (var i = 0; i < 5; i++) {
    // 注意有一層額外的閉包
    tasks[tasks.length] = (function (i) {
        return function () {
            console.log("Current cursor is at " + i);
        };
    })(i);
}

var len = tasks.length;
while (len--) {
    tasks[len]();
}

javascriptvar emptyFunction = function () {};

javascriptvar EMPTY_FUNCTION = function () {};

function MyClass() {
}

MyClass.prototype.abstractMethod = EMPTY_FUNCTION;
MyClass.prototype.hooks.before = EMPTY_FUNCTION;
MyClass.prototype.hooks.after = EMPTY_FUNCTION;

javascript/**
 * 構建類之間的繼承關系
 * 
 * @param {Function} subClass 子類函數
 * @param {Function} superClass 父類函數
 */
function inherits(subClass, superClass) {
    var F = new Function();
    F.prototype = superClass.prototype;
    subClass.prototype = new F();
    subClass.prototype.constructor = subClass;
}

javascriptfunction Animal(name) {
    this.name = name;
}

// 直接prototype等于對象時，需要修正constructor
Animal.prototype = {
    constructor: Animal,

    jump: function () {
        alert("animal " + this.name + " jump");
    }
};

// 這種方式擴展prototype則無需理會constructor
Animal.prototype.jump = function () {
    alert("animal " + this.name + " jump");
};

javascriptfunction TextNode(value, engine) {
    this.value = value;
    this.engine = engine;
}

TextNode.prototype.clone = function () {
    return this;
};

javascriptvar handler = new Function("x", "y", "return x + y;");
var result = handler($("#x").val(), $("#y").val());

javascripttry {
    delete o.x;
}
catch (deleteError) {
    o.x = null;
}

javascriptfunction Tree(datasource) {
    this.datasource = datasource;
}

Tree.prototype.selectNode = function (id) {
    // 從datasource中找出節點對象
    var node = this.findNode(id);
    if (node) {
        node.selected = true;
        this.flushView();
    }
};

javascriptfunction Tree(datasource) {
    this.datasource = datasource;
    this.selectedNodeIndex = {};
}

Tree.prototype.selectNode = function (id) {
    // 從datasource中找出節點對象
    var node = this.findNode(id);
    if (node) {
        this.selectedNodeIndex[id] = true;
        this.flushView();
    }
};