前端代碼註釋

代碼爲何須要註釋

「代碼千萬行，註釋第一行；編程不規範，同事兩行淚；」代碼註釋爲啥很重要呢？如下是個人一些想法:

• 提升代碼可讀性

《黑客與畫家》裏面有句話「程序寫出來是給人看的，附帶能在機器上運行」。既然是給人看的，我以爲有兩個方面就比較重要。1、代碼寫的好，好的代碼依賴於coder的代碼功底。要寫出好的代碼，須要多修煉內功。2、註釋寫的好。就像咱們上學的時候看文言文，字基本都認識，可是連在一塊兒就是不知道什麼意思。這個時候就依賴於註釋了，註釋能把文言文中難懂的詞彙翻譯成白話。代碼註釋也是同樣的道理，用來解釋代碼的意義。

• 快速的導出接口文檔

若是須要和外部對接時，優秀的代碼註釋能夠經過 jsdoc快速導出接口文檔

• 提升代碼編寫效率和代碼準確性

9102了大部分IDE都能根據註釋去分析，提供一寫智能提示，提升代碼編寫效率，下降咱們代碼的出錯率。

代碼註釋的原則

一個原則是「as short as possible，as long as necessary 」。代碼註釋是必須的，可是要避免註釋過多過濫，不要爲了註釋而註釋。咱們應該提升修煉好內容，提升代碼自己的可讀性。如下是一些須要添加註釋的地方：

• 文件描述註釋
• 類描述註釋
• 組件暴露出來的公共方法，工具類的方法、業務實現的關鍵方法
• 關鍵變量、關鍵常量、TODO、約定的特殊標識
• 解釋複雜業務的實現邏輯

文件註釋

文件頭部增長文件註釋，用於描述文件的基本信息。便於閱讀代碼時，快速的理解該文件的功能。 主要包含如下字段：

• @description 文件描述
• @author 做者
• @date 建立時間
• @lastModifiedBy 最新的變動人
• @lastModifiedTime 最新的更新時間

/**
 * @description 文件幹啥用的
 * @author CaiCai
 * @date 2019-2-20 16:16:52
 * @lastModifiedBy CaiCai·
 * @lastModifiedTime  2019-2-25 20:07:43
 */
複製代碼

類的註釋

使用ES的語法Class定義一個類，主要包含以下字段：

• @description 一個參數描述類的說明。
• @property 描述public的實例屬性。有三個參數，第一個參數表示屬性的數據類型，用 {} 包含。第二個參數表示屬性名。第三個參數用來表示屬性的說明。 屬性名和屬性說明用‘ - ’連字符來鏈接，鏈接符先後須要空格
• @hideconstructor 無參數，表示該類隱藏了構造函數。即定義中無構造函數，使用默認構造函數。有構造函數時，則不能使用該標識
• @param 描述建立實例時的「參數」。有三個參數，第一個參數表示「參數」的數據類型，用 {} 包含。第二個參數表示「參數」名。第三個參數表示「參數」的說明。 「參數」和「參數」說明用‘ - ’連字符來鏈接，鏈接符先後須要空格
• @extends 描述類繼承自那個父類
• @static 標識類的靜態方法

/**
 * @description 一個參數用來描述類的主要功能
 * @property {string} props - 類的屬性
 * @param {string} arg - 建立實例時的參數
 * @extends Parent
 */
class Test extends Parent {
    /**
     * @description 這是個靜態方法
     * @returns { void }
     * @static
     */
    static testStaticMethod() {
    }
    constructor(arg) {
        super()
        this.props = arg
    }
}
複製代碼

JSDOC生成的接口文檔：

Test類，經過JSDOC生成的接口文檔

方法註釋

• @description 一個參數用來描述方法說明。
• @param 描述建立實例時的「參數」。有三個參數，第一個參數表示「參數」的數據類型，用 {} 包含。第二個參數表示「參數」名。第三個參數表示「參數」的說明。 「參數」和「參數」說明用‘ - ’連字符來鏈接，鏈接符先後須要空格。若是「參數」是個對象則用多個@param 來聲明。 「參數」名用[]括起來是,該參數是可選參數，[]內能夠用=設置默認參數。「參數」是個數組時，數據類型後添加[]。
• @returns 標識方法的返回值 包含兩個參數。 第一個參數是返回的數據類型，可返回多種數據類型，用|分割。第二個參數是返回值的說明。
• @example 經過例子來解釋方法怎麼用。

/**
 * @description 保存用戶信息
 * @param { object } user - 用戶
 * @param { string } user.name - 用戶名
 * @param { number } user.age - 年齡
 * @param { boolean } [user.isMarried = false] - 是否已婚
 * @param { object[] } [exGirlFriends] - 前女朋友
 * @param { string } exGirlFriends[].name 前女朋友名字
 * @param { number } exGirlFriends[].age 前女朋友年齡
 * @param { number } [id] - 用戶ID
 * @returns { (number|string) } 用戶ID
 * @example
 * updateUserInfo({name:'CaiCai',age:26,isMarried:true})
 * // => 1
 */
function updateUserInfo() {

}
複製代碼

updateUserInfo方法，經過JSDOC生成的接口文檔

單行註釋

標識關鍵的變量、關鍵常量、TODO、約定的特殊標識等。單行註釋用「//」開頭，單行註釋符後留一個空格。

// 這是單行註釋
複製代碼

多行註釋

描述關鍵代碼或解釋複雜業務的實現邏輯，提升代碼可讀性。 多行註釋用「/*」開始，用「*/」結束。 開頭和結束的*對齊

/*
 這是多行註釋
 這是第二行
 */
複製代碼

以上是我對註釋的一些思考，不適合全部人。你們能夠在評論區，一塊兒討論「好的註釋」。

參考文檔：
註釋那些事兒 - 前端代碼質量系列文章（一）
JSDOC 官方文檔
js/javascript代碼註釋規範與示例
Javascript註釋規範