前端註釋規範

可以通過設置編輯器來設置出一致的註釋模式。

1. HTML註釋

• 模塊註釋

<!-- 訂單詳情模塊 -->

• 區塊註釋

<!-- 
    @name: 訂單詳情
    @description: 主要是訂單詳情頁面
    @author: fjw([email protected])
-->

2. CSS註釋

• 組件塊和子組件塊以及聲明塊之間使用一空行分隔，子組件塊之間三空行分隔；

/* ==========================================================================
組件塊
============================================================================ */

/* 子組件塊
============================================================================ */
.selector {
    padding: 15px;
    margin-bottom: 15px;
}

/* 子組件塊
============================================================================ */
.selector-secondary {
    display: block; /* 註釋*/
}

.selector-three {
    display: span;
}

3. JavaScript註釋

• 單行註釋：
  獨佔一行，後跟一個空格，縮進與下一行被註釋說明的代碼一致。

• 多行註釋：
  避免使用 /.../ 這樣的多行註釋。有多行註釋內容時，使用多個單行註釋。

• 函數/方法註釋：

  • 必須包含函數的說明；
  • 有參數和返回值時，必須有註釋標誌；
  • 參數和返回值必須包含類型信息和說明；
  • 當函數是內部函數，外部不可以訪問時，可以使用@inner來標識；
  • 示範：

    /**
    * 函數描述
    *
    * @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
        };
    }
    

4. 文件註釋

• 文件註釋用於告訴不熟悉這段代碼的讀者這個文件中包含哪些東西。
• 文件註釋要標明作者、文件版本、創建/修改時間、重大版本修改記錄；
• 示範：

  /**
  * @fileoverview Description of file, its uses and information
  * about its dependencies.
  * @author [email protected] (Firstname Lastname)
  * Copyright 2019 QQ Inc. All Rights Reserved.
  */
  

!!! 以上規則僅供參考