摘要：優(yōu)秀的代碼注釋可以提高代碼可讀性，當(dāng)然優(yōu)秀的命名規(guī)范也可以啦。表示函數(shù)是異步的。行注釋行注釋的話，應(yīng)該不用做太多的解釋，直接用注釋相關(guān)信息就啦。

可能現(xiàn)在不管大家去面試還是在公司上班都會(huì)涉及到代碼可讀性，或者是代碼規(guī)范。優(yōu)秀的代碼注釋可以提高代碼可讀性，當(dāng)然優(yōu)秀的命名規(guī)范也可以啦。我們這里就討論一下代碼注釋。代碼注釋可能就相當(dāng)于產(chǎn)品使用說(shuō)明書，當(dāng)別人看到你的代碼的時(shí)候，知道你的代碼是干嘛的，是怎么使用的。我們所熟悉的可能就是 // 是單行注釋，/***/ 是多行注釋，下面我們就來(lái)聊一聊代碼注釋!

關(guān)于文件注釋可能很多同學(xué)都沒(méi)有用過(guò)，但大家都多多少少有看過(guò)文件注釋。

比如我們熟悉的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
*/

在這里我們可以大概了解到版權(quán)或者作者，又或者開源協(xié)議等信息。

在日常工作中我們也經(jīng)?？吹竭@樣的文件注釋：

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

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

插件：koroFileHeader

其實(shí)文件注釋也有一些規(guī)范的：

/**
 * @file 對(duì)文件的描述，用于文件的頭部
 * @author  [] 代碼的作者,在姓名后面用尖括號(hào)加上郵箱會(huì)被自動(dòng)轉(zhuǎn)成 mailto: 的鏈接
 * @copyright  與@file結(jié)合使用，說(shuō)明版權(quán)相關(guān)的信息
 * @license  說(shuō)明許可證相關(guān)的信息
 * @version 版本號(hào)
 */

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

代碼塊注釋，也可以說(shuō)是方法注釋，可以提現(xiàn)出方法的用處，已經(jīng)所需參數(shù)，返回值等；大大提高代碼的可讀性！

下面就是一個(gè)簡(jiǎn)單的方法注釋：

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

下面我就舉幾個(gè)例子：

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
}

通過(guò)上面幾個(gè)例子是不是很快的知道各代碼的作用是什么，需要的參數(shù)是什么，這樣子一來(lái)代碼就可以很容易的被同事或者說(shuō)下一個(gè)接手維護(hù)的人看懂！對(duì)于方法描述，參數(shù)描述就可以看團(tuán)隊(duì)公司來(lái)定是寫成英語(yǔ)還是中文了。

下面是一些常用的注釋標(biāo)簽

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

還有很多，大家可以去 jsDoc 看相應(yīng)的一些規(guī)范。

行注釋的話，應(yīng)該不用做太多的解釋，直接用 // 注釋相關(guān)信息就OK啦。當(dāng)然 // TODO 習(xí)慣用這個(gè)的話也是非常不錯(cuò)的喲！

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

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

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

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


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


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

我自己運(yùn)營(yíng)的公眾號(hào)，記錄我自己的成長(zhǎng)！

公眾號(hào)：前端曰

公眾號(hào)ID：js-say

ps：是(yue)不是(ri)