摘要：優秀的代碼注釋可以提高代碼可讀性，當然優秀的命名規范也可以啦。表示函數是異步的。行注釋行注釋的話，應該不用做太多的解釋，直接用注釋相關信息就啦。

可能現在不管大家去面試還是在公司上班都會涉及到代碼可讀性，或者是代碼規范。優秀的代碼注釋可以提高代碼可讀性，當然優秀的命名規范也可以啦。我們這里就討論一下代碼注釋。代碼注釋可能就相當于產品使用說明書，當別人看到你的代碼的時候，知道你的代碼是干嘛的，是怎么使用的。我們所熟悉的可能就是 // 是單行注釋，/***/ 是多行注釋，下面我們就來聊一聊代碼注釋!

關于文件注釋可能很多同學都沒有用過，但大家都多多少少有看過文件注釋。

比如我們熟悉的jQuery/vuejs/reactjs的文件注釋：

// jQuery的文件注釋
/*!
 * jQuery JavaScript Library v1.11.3
 * http://jquery.com/
 *
 * Includes Sizzle.js
 * http://sizzlejs.com/
 *
 * Copyright 2005, 2014 jQuery Foundation, Inc. and other contributors
 * Released under the MIT license
 * http://jquery.org/license
 *
 * Date: 2015-04-28T16:19Z
 */

// vuejs的文件注釋
/*!
 * Vue.js v2.6.10
 * (c) 2014-2019 Evan You
 * Released under the MIT License.
 */

// reactjs的文件注釋
/** @license React v16.8.6
 * react-dom.production.min.js
 *
 * Copyright (c) Facebook, Inc. and its affiliates.
 *
 * This source code is licensed under the MIT license found in the
 * LICENSE file in the root directory of this source tree.
 */
/*
 Modernizr 3.0.0pre (Custom Build) | MIT
*/

在這里我們可以大概了解到版權或者作者，又或者開源協議等信息。

在日常工作中我們也經常看到這樣的文件注釋：

/*
 * @Description: Description
 * @Author: js-say
 * @Date: 2019-05-23 17:57:10
 * @LastEditTime: 2019-05-23 17:57:10
 * @LastEditors: js-say
 */

這樣的注釋包括了描述、作者、創建時間、更新時間等。這樣大家一眼就能知道這個文件大概實現了什么功能，開始是誰寫的，最后維護的是誰。文件注釋其實可以看自己公司要求和規范來寫！使用 vs-code 的話有一個插件可以快捷生成文件注釋，當然方法注釋也是可以的。這里就只給插件名字啦，具體怎么使用大家可以自己研究一下！

插件：koroFileHeader

其實文件注釋也有一些規范的：

/**
 * @file 對文件的描述，用于文件的頭部
 * @author  [] 代碼的作者,在姓名后面用尖括號加上郵箱會被自動轉成 mailto: 的鏈接
 * @copyright  與@file結合使用，說明版權相關的信息
 * @license  說明許可證相關的信息
 * @version 版本號
 */

大致一個文件注釋可以是這樣子的，還可以有很多比如 @desc 描述之類的，大家可以參考 jsDoc

代碼塊注釋，也可以說是方法注釋，可以提現出方法的用處，已經所需參數，返回值等；大大提高代碼的可讀性！

下面就是一個簡單的方法注釋：

/**
 * Represents a book.
 * @constructor
 * @param {string} title - The title of the book.
 * @param {string} author - The author of the book.
 */
function Book(title, author) {
  // ...
}

下面我就舉幾個例子：

class 的注釋：

/** Class representing a point. */
class Point {
    /**
     * Create a point.
     * @param {number} x - The x value.
     * @param {number} y - The y value.
     */
    constructor(x, y) {
        // ...
    }

    /**
     * Get the x value.
     * @return {number} The x value.
     */
    getX() {
        // ...
    }

    /**
     * Get the y value.
     * @return {number} The y value.
     */
    getY() {
        // ...
    }

    /**
     * Convert a string containing two comma-separated numbers into a point.
     * @param {string} str - The string containing two comma-separated numbers.
     * @return {Point} A Point object.
     */
    static fromString(str) {
        // ...
    }
}

class 繼承

/**
 * Class representing a dot.
 * @extends Point
 */
class Dot extends Point {
    /**
     * Create a dot.
     * @param {number} x - The x value.
     * @param {number} y - The y value.
     * @param {number} width - The width of the dot, in pixels.
     */
    constructor(x, y, width) {
        // ...
    }

    /**
     * Get the dot"s width.
     * @return {number} The dot"s width, in pixels.
     */
    getWidth() {
        // ...
    }
}

module 注釋

/** @module color/mixer */

/** The name of the module. */
export const name = "mixer";

/** The most recent blended color. */
export var lastColor = null;

/**
 * Blend two colors together.
 * @param {string} color1 - The first color, in hexadecimal format.
 * @param {string} color2 - The second color, in hexadecimal format.
 * @return {string} The blended color.
 */
export function blend(color1, color2) {}

// convert color to array of RGB values (0-255)
function rgbify(color) {}

export {
    /**
     * Get the red, green, and blue values of a color.
     * @function
     * @param {string} color - A color, in hexadecimal format.
     * @returns {Array.} An array of the red, green, and blue values,
     * each ranging from 0 to 255.
     */
    rgbify as toRgb
}

通過上面幾個例子是不是很快的知道各代碼的作用是什么，需要的參數是什么，這樣子一來代碼就可以很容易的被同事或者說下一個接手維護的人看懂！對于方法描述，參數描述就可以看團隊公司來定是寫成英語還是中文了。

下面是一些常用的注釋標簽

/**
 * @author? 作者，方便定位? ? 
 * @class（同義詞：@constructor）標記類和構造函數? ? 
 * @constant @const常量標記? ? 
 * @description（同義詞：@desc） 對內容進行描述????
 * @module 模塊名稱? ? 
 * @enum 枚舉類型標記? ? 
 * @global 全局對象標記? ? 
 * @param 函數參數標記? ? 
 * @returns（同義詞：@return）函數返回標記? ? 
 * @this this指向標記? ? 
 * @see 參考鏈接? ? 
 * @memberof 標記模塊間的從屬關系? ? 
 * @event 在模板中標記可以被觸發的事件，與@fire配合使用
 * @alias 將成員視為具有不同的名稱。
 * @Async 表示函數是異步的。
 * @augments（同義詞：@extends）指示符號從父符號繼承并添加到父符號。
 * @borrows 此對象使用來自另一個對象的內容。
 * @callback 回調函數。
 * @copyright 版權信息。
 * @default （同義詞: @defaultvalue） 默認值。
 * @example 示例。
 */

還有很多，大家可以去 jsDoc 看相應的一些規范。

行注釋的話，應該不用做太多的解釋，直接用 // 注釋相關信息就OK啦。當然 // TODO 習慣用這個的話也是非常不錯的喲！

/**
 *                    _ooOoo_
 *                   o8888888o
 *                   88" . "88
 *                   (| -_- |)
 *                    O = /O
 *                ____/`---"\____
 *              .   " | |// `.
 *               / ||| : |||// 
 *             / _||||| -:- |||||- 
 *               | |  - /// | |
 *             | \_| ""---/"" | |
 *               .-\__ `-` ___/-. /
 *           ___`. ." /--.-- `. . __
 *        ."" "< `.___\_<|>_/___." >""".
 *       | | : `- `.;` _ /`;.`/ - ` : | |
 *           `-. \_ __ /__ _/ .-` / /
 * ======`-.____`-.___\_____/___.-`____.-"======
 *                    `=---="
 *
 * .............................................
 *          佛祖保佑             永無BUG
 */

/**
 *  佛曰:
 *          寫字樓里寫字間，寫字間里程序員；
 *          程序人員寫程序，又拿程序換酒錢。
 *          酒醒只在網上坐，酒醉還來網下眠；
 *          酒醉酒醒日復日，網上網下年復年。
 *          但愿老死電腦間，不愿鞠躬老板前；
 *          奔馳寶馬貴者趣，公交自行程序員。
 *          別人笑我忒瘋癲，我笑自己命太賤；
 *          不見滿街漂亮妹，哪個歸得程序員？
 */

/**
 * _ooOoo_
 * o8888888o
 * 88" . "88
 * (| -_- |)
 *  O = /O
 * ___/`---"\____
 * .   " | |// `.
 * / ||| : |||// 
 * / _||||| -:- |||||- 
 * | |  - /// | |
 * | \_| ""---/"" | |
 *  .-\__ `-` ___/-. /
 * ___`. ." /--.-- `. . __
 * ."" "< `.___\_<|>_/___." >""".
 * | | : `- `.;` _ /`;.`/ - ` : | |
 *   `-. \_ __ /__ _/ .-` / /
 * ======`-.____`-.___\_____/___.-`____.-"======
 * `=---="
 *          .............................................
 *           佛曰：bug泛濫，我已癱瘓！
 */

/***
 *      ┌─┐       ┌─┐ + +
 *   ┌──┘ ┴───────┘ ┴──┐++
 *   │                 │
 *   │       ───       │++ + + +
 *   ███████───███████ │+
 *   │                 │+
 *   │       ─┴─       │
 *   │                 │
 *   └───┐         ┌───┘
 *       │         │
 *       │         │   + +
 *       │         │
 *       │         └──────────────┐
 *       │                        │
 *       │                        ├─┐
 *       │                        ┌─┘
 *       │                        │
 *       └─┐  ┐  ┌───────┬──┐  ┌──┘  + + + +
 *         │ ─┤ ─┤       │ ─┤ ─┤
 *         └──┴──┘       └──┴──┘  + + + +
 *                神獸保佑
 *               代碼無BUG!
 */


/***
 *                  ___====-_  _-====___
 *            _--^^^#####//      #####^^^--_
 *         _-^##########// (    ) ##########^-_
 *        -############//  |^^/|  ############-
 *      _/############//   (@::@)   ############\_
 *     /#############((     //     ))#############
 *    -###############    (oo)    //###############-
 *   -#################  / VV   //#################-
 *  -###################/      //###################-
 * _#/|##########/######(   /   )######/##########|#_
 * |/ |#/#/#//  #/##  |  |  /##/#/  /#/#/#| |
 * `  |/  V  V  `   V  #| |  | |/#/  V   "  V  V  |  "
 *    `   `  `      `   / | |  | |    "      "  "   "
 *                     (  | |  | |  )
 *                    __ | |  | | /__
 *                   (vvv(VVV)(VVV)vvv)                
 *                        神獸保佑
 *                       代碼無BUG!
 */


/***
 *
 *
 *                                                    __----~~~~~~~~~~~------___
 *                                   .  .   ~~//====......          __--~ ~~
 *                   -.            \_|//     |||  ~~~~~~::::... /~
 *                ___-==_       _-~o~  /    |||              _/~~-
 *        __---~~~.==~||=_    -_--~/_-~|-   |           _/~
 *    _-~~     .=~    |  -_    "-~7  /-   /  ||          /
 *  .~       .~       |    -_    /  /-   /   ||         /
 * /  ____  /         |      ~-_/  /|- _/   .||        /
 * |~~    ~~|--~~~~--_      ~==-/   | ~--===~~        .
 *          "         ~-|      /|    |-~~~       __--~~
 *                      |-~~-_/ |    |   ~\_   _-~            /
 *                           /       \__   /~                \__
 *                       _--~ _/ | .-~~____--~-/                  ~~==.
 *                      ((->/~   ".|||" -_|    ~~-/ ,              . _||
 *                                 -_     ~      ~~---l__i__i__i--~~_/
 *                                 _-~-__   ~)  --______________--~~
 *                               //.-~~~-~_--~- |-------~~~~~~~~
 *                                      //.-~~~--
 *                               神獸保佑
 *                              代碼無BUG!
 */ 

我自己運營的公眾號，記錄我自己的成長！

公眾號：前端曰

公眾號ID：js-say

ps：是(yue)不是(ri)