摘要：包含描述與指定所有參數(shù)和返回值的類型和值的注釋標(biāo)簽。返回值的類型和描述或者更多示例更多請(qǐng)參考以下網(wǎng)站為本文參考，歡迎留言糾正。注解注釋原文代碼注釋規(guī)范與示例注釋

做為一個(gè)有情懷的Coder，最近收集了一下JavaScript代碼注釋范例，希望能夠幫助大家擼得一手妖媚而又放蕩的Bug。

使用 // 作為單行注釋。

單行注釋符后與注釋內(nèi)容保留一個(gè)空格。

//bad comments
// good comments

單行注釋需要在說(shuō)明的代碼之上另起一行，并且在注釋前插入空行。

function isType(content, expect) {

    // good
    // Using Object.prototype.toString to judge data types.
    let type = Object.prototype.toString.call(content).replace(/[objects|]/g, "");

    return type === expect;
}
// bad
console.log(isType("hello", "String"));       // return true

帶有 // FIXME: 或 // TODO: 的前綴的注釋可以幫助其他開發(fā)者快速了解這是一個(gè)需要復(fù)查的問(wèn)題，或是給需要實(shí)現(xiàn)的功能提供一個(gè)解決方式。這將有別于常見的注釋，因?yàn)樗鼈兪强刹僮鞯?。使?FIXME -- need to figure this out 或者 TODO -- need to implement。

使用 // FIXME: 標(biāo)注問(wèn)題。

class Calculator {
    constructor() {
        // FIXME: shouldn"t use a global here
        total = 0;
    }
}

使用 // TODO: 標(biāo)注問(wèn)題的解決方式。

// Support: IE, Opera, Webkit
// TODO: identify versions
// getElementById can match elements by name instead of ID
if ( newContext && (elem = newContext.getElementById( m )) &&
    contains( context, elem ) &&
    elem.id === m ) {

    results.push( elem );
    return results;
}

多行注釋星號(hào) * 對(duì)齊，并且注釋內(nèi)容不要寫在起始符號(hào) /**與結(jié)束符號(hào) */ 所在行。

// bad
/* matches from matchExpr["CHILD"]
  1 type (only|nth|...)
   2 what (child|of-type)
*/

// good
/* 
    matches from matchExpr["CHILD"]
    1 type (only|nth|...)
    2 what (child|of-type)
 */

使用 /* ... */ 作為文件注釋。

文件注釋主要包含：概要介紹、版本信息、版權(quán)聲明、開源協(xié)議、修改時(shí)間等說(shuō)明內(nèi)容。

React.js

/** @license React v16.4.0
 * react.development.js
 *
 * Copyright (c) 2013-present, Facebook, Inc.
 *
 * This source code is licensed under the MIT license found in the
 * LICENSE file in the root directory of this source tree.
 */

jQuery.js

/*!
 * jQuery JavaScript Library v3.3.1
 * https://jquery.com/
 *
 * Includes Sizzle.js
 * https://sizzlejs.com/
 *
 * Copyright JS Foundation and other contributors
 * Released under the MIT license
 * https://jquery.org/license
 *
 * Date: 2018-01-20T17:24Z
 */

開源項(xiàng)目的開發(fā)版本與生產(chǎn)版本中都會(huì)保留文件注釋，且必須對(duì)引用的其他開源代碼進(jìn)行說(shuō)明。

使用 /** ... */ 作為文檔API注釋。包含描述與指定所有參數(shù)和返回值的類型和值的注釋標(biāo)簽。

/**
 * Maps children that are typically specified as `props.children`.
 *
 * See https://reactjs.org/docs/react-api.html#react.children.map
 *
 * The provided mapFunction(child, key, index) will be called for each
 * leaf child.
 *
 * @param {?*} children Children tree container.
 * @param {function(*, int)} func The map function.
 * @param {*} context Context for mapFunction.
 * @return {object} Object containing the ordered map of results.
 */
function mapChildren(children, func, context) {

  if (children == null) {
    return children;
  }

  var result = [];
  mapIntoWithKeyPrefixInternal(children, result, null, func, context);

  return result;
}

@param 指定參數(shù)的名稱。您還可以包含參數(shù)的數(shù)據(jù)類型，使用大括號(hào)括起來(lái)，和參數(shù)的描述。

/**
 * @param content
 */

注釋變量名 和 變量類型

/**
 * @param {String} type
 */

注釋變量名、變量類型 和 變量說(shuō)明

/**
 * @param {String} attrs Pipe-separated list of attributes
 */

連字符可以使注釋閱讀友好

參數(shù)變量名與參數(shù)說(shuō)明之間使用連字符 -

/**
 * @param {object} partialState - Next partial state to be merged with state.
 */

對(duì)象參數(shù)屬性描述

描述一個(gè)對(duì)象參數(shù)的屬性

/**
 * @param {Object} employee - The employee who is responsible for the project.
 * @param {string} employee.name - The name of the employee.
 * @param {string} employee.department - The employee"s department.
 */

同樣，可以聯(lián)想到如果假如 employee 參數(shù)是一個(gè)數(shù)組，這個(gè)數(shù)組中包含 name 和 department 元素，那么可以這么描述。

描述參數(shù)的屬性值在數(shù)組中

/**
 * Assign the project to a list of employees.
 * @param {Object[]} employees - The employees who are responsible for the project.
 * @param {string} employees[].name - The name of an employee.
 * @param {string} employees[].department - The employee"s department.
 */

可選參數(shù)和默認(rèn)值

JSDoc可選參數(shù)

/**
 * @param {string} key - Key to be escaped.
 */

JSDoc可選參數(shù)和默認(rèn)值

/**
 * @param {Number} [index=0] - Somebody"s name.
 */

Google Closure Compiler 可選參數(shù)

/**
 * @param {string=} somebody - Somebody"s name.
 */

多種類型參數(shù)

下面的例子演示了如何使用類型的表達(dá)式來(lái)表示一個(gè)參數(shù)可以接受多種類型（或任何類型），還有一個(gè)參數(shù)可以被多次使用。

/**
 * @param {(string|string[])} [somebody=John Doe] - Somebody"s name, or an array of names.
 */

允許任何類型

/**
 * @param {*} component - A component that could contain a manual key.
 */

可重復(fù)使用的參數(shù)

所有可變參數(shù)都是數(shù)字

/**
 * @param {...number} num - A positive or negative number.
 */

管道字符 | 用來(lái)連接聯(lián)合類型，聯(lián)合類型用來(lái)表明參數(shù)可以有多個(gè)類型

/** 
 * @param {string|null|undefined} str 
 */

因?yàn)閰?shù)是否非空很常見，因此有一個(gè)快捷方式用來(lái)標(biāo)明聯(lián)合類型是否包含 null

/** 
 * @param {?string} str1 is a string or null 
 * @param {?string|undefined} str2 is a string, null, or undefined. The ? 
 *     prefix does not include undefined, so it must be included explicitly. 
 */

除了基本類型的所有類型，如Object,Array和HTMLDocument默認(rèn)都可以為空，這些類型統(tǒng)稱為對(duì)象類型，因此 ? 前綴對(duì)對(duì)象類型是多余的

/** 
 * @param {Document} doc1 is a Document or null because object types are nullable by default. 
 * @param {?Document} doc2 is also a Document or null. 
 */

如果要聲明一個(gè)非空對(duì)象對(duì)開，可以用 ! 前綴

/** 
 * @param {!Array} array must be a non-null Array 
 * @param {!Array|undefined} maybeArray is an Array or undefined, but 
 *     cannot be null. 
 */

盡管一個(gè)方法中可以有任意多個(gè)可選參數(shù)，但是可選參數(shù)不應(yīng)該出現(xiàn)在必須參數(shù)之前，如果出現(xiàn)在之前，代碼必須寫成如下形式

/** 
 * @param {string=} title Defaults to "New Spreadsheet". 
 * @param {string} author 
 */

大量的可靠參數(shù)，最好將其它移到一個(gè)必須的對(duì)象參數(shù)中

/**  
 * @param {{author: (string|undefined), title: (string|undefined), numRows: (number|undefined)  
 */

不定數(shù)量參數(shù)

Closure不定數(shù)量參數(shù)

/** 
 * @param {string} category 
 * @param {...} purchases 
 * @return {number} 
 */

注釋函數(shù)類型值的可選和可變參數(shù)

/** 
 * @param {function(string, string=)} ……
 * @param {function(string, ...[number]): number} ……
 */

回調(diào)函數(shù)

使用 @callback 標(biāo)簽來(lái)定義回調(diào)類型，回調(diào)類型包含到 @param 中。

/**
 * This callback type is called `requestCallback` and is displayed as a global symbol.
 *
 * @callback requestCallback
 * @param {number} responseCode
 * @param {string} responseMessage
 */

/**
 * Does something asynchronously and executes the callback on completion.
 * @param {requestCallback} cb - The callback that handles the response.
 */

@return / @returns 返回值的類型和描述

/**
 * @return {object} Object containing the ordered map of results.
 * @return {!number} The number of children in this subtree.
 */

或者

/**
 * @returns {boolean} True if mounted, false otherwise.
 * @returns {Element|Object|Boolean} The input node if acceptable, otherwise a falsy value
 */

更多示例

/**
 * @param {?Function(*, Boolean)} callback - To invoke upon traversing each child.
 * @param {String|Number} ref
 * @param {?*} children - Children tree container.
 * @param {Element|Object=} context
 * @param {!ArrayLike} nodes
 * @returns {Element|Object|Boolean} The input node if acceptable, otherwise a falsy value
 */

/**
 * @param {?*} children - Children tree container.
 * @param {!string} nameSoFar - Name of the key path so far.
 * @param {!function} callback - Callback to invoke with each child found.
 * @return {!number} The number of children in this subtree.
 */

以下網(wǎng)站為本文參考，歡迎留言糾正。

YUIDoc Syntax Reference
@use JSDoc
Closure javascript注解
Airbnb JavaScript Style Guide() { - 注釋
原文Airbnb JavaScript Style Guide() {
js/javascript代碼注釋規(guī)范與示例
Js注釋