【規範】前端編碼規範——註釋規範

文件申明

頂部添加文件申明信息，包括文件描述、原始做者，若是有更新，則須要添加更新內容、更新做者和更新時間。

/**
 * @description: 說明文字
 * @author: 張三
 */

/**
 * @description: 說明文字
 * @author: 張三
 * @update: 更新內容 by 李四 2013-04-13 18:32
 */

單行註釋與多行註釋

不管是單行註釋仍是多行註釋，註釋中的每一行長度都不能超過 40 個漢字，或者 80 個英文字符。

單行註釋

/* this is a short comment */

多行註釋

/*
* this is comment line 1.
* this is comment line 2.
*/

函數或方法註釋

/**
 * 這是一個求和函數
 * @param  {Number} a 第一個數字
 * @param  {Number} b 第二個數字
 * @return {Number}   返回兩個數字之和
 */
var sum = function(a, b) {
    return a + b;
}

模塊註釋

模塊註釋必須單獨寫在一行。

/* 模塊：xxxxxx by 張三 */
...
/* 模塊：xxxxxx by 張三 */

樣式區塊註釋

/* header */
...
/* footer */
...
/* banner */
...