強迫症->js註釋規範

以前本身寫代碼，就像人心渙散，徹底沒有一種規範。這種自由，會讓本身寫的東西時常變化。也很不利於團隊協做開發。通過最近一段時間的開發，和對一些註釋風格的參考，造成了本身想去使用的註釋規範。

js的組織是模塊化，一個模塊對應一個js文件。

模塊功能描述說明：

/**
 * ------------------------------------------------------------------
 * 模塊描述說明
 * ------------------------------------------------------------------
 */

我喜歡開始和結束各空一行，中間是描述內容。

模塊內的小函數方法歸類：

/**
 * 小函數方法歸類說明，這些零散的小函數方法放在一塊兒 對應 一個業務方法邏輯
 * ------------------------------------------------------------------
 */

把一個業務方法中抽取出來的小函數放在一塊兒，便於查找。

單個函數方法：

/**
 * 函數功能簡述
 *
 * 具體描述一些細節
 *
 * @param    {string}  address     地址
 * @param    {array}   com         商品數組
 * @param    {string}  pay_status  支付方式
 * @returns  void
 *
 * @date     2014-04-12
 * @author   QETHAN<qinbinyang@zuijiao.net>
 */

開發中使用的是PhpStorm IDE, 每次建立一個js新文件，文件內容頭部會根據配置文件模板去自動加上一些註釋信息。我配置的是 日期 和 做者。如今是一我的開發，因此上邊註釋中的日期和做者 我通常不會在函數中去加上。可是，若是其餘人蔘與進來了，本身修改的是別人的代碼，就要更新添加這些註釋信息。

單行註釋：

//這是一條單行註釋

有些人喜歡這樣 // 這是一條單行註釋 雙斜槓後邊會加一個空格。我不認同。喜歡幹練清晰簡潔，在適合的時候，就必定會這樣作。

單個函數方法中變量註釋：

//商品屬性變量(一組變量描述)
    //商品名字(單個變量註釋)
var name = $(item).find('.js-name').val(),
    //商品數量
    count = $(item).find('.js-count').text(),
    //商品單價
    price = $(item).find('.js-price').val();

有些喜歡註釋放在單個變量後邊。若是變量註釋有點長，就不太好了。放在上邊，比較省心，清晰。

單個函數方法中代碼片斷註釋：

/*
 | 代碼片斷的描述說明
 */

if, foreach, addEventListener ... 這些代碼片斷的時候

註釋中縮進 必須使用空格。保證各類環境下排版的一致性。

@use JSDoc

<持續維護更新...>