代碼註釋的藝術，不再怕被說代碼可讀性差啦！

時間  2019-11-08
標籤 代碼 註釋 藝術 不再 可讀性 简体版
原文   原文鏈接

前言

可能如今無論你們去面試仍是在公司上班都會涉及到代碼可讀性，或者是代碼規範。優秀的代碼註釋能夠提升代碼可讀性，固然優秀的命名規範也能夠啦。咱們這裏就討論一下代碼註釋。代碼註釋可能就至關於產品使用說明書，當別人看到你的代碼的時候，知道你的代碼是幹嗎的，是怎麼使用的。咱們所熟悉的可能就是 // 是單行註釋，/***/ 是多行註釋，下面咱們就來聊一聊代碼註釋!javascript

文件註釋

關於文件註釋可能不少同窗都沒有用過，但你們都多多少少有看過文件註釋。前端

好比咱們熟悉的jQuery/vuejs/reactjs的文件註釋：vue

// 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
*/

在這裏咱們能夠大概瞭解到版權或者做者，又或者開源協議等信息。java

在平常工做中咱們也常常看到這樣的文件註釋：react

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

這樣的註釋包括了描述、做者、建立時間、更新時間等。這樣你們一眼就能知道這個文件大概實現了什麼功能，開始是誰寫的，最後維護的是誰。文件註釋其實能夠看本身公司要求和規範來寫！使用 vs-code 的話有一個插件能夠快捷生成文件註釋，固然方法註釋也是能夠的。這裏就只給插件名字啦，具體怎麼使用你們能夠本身研究一下！jquery

插件：koroFileHeadergit

其實文件註釋也有一些規範的：程序員

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

大體一個文件註釋能夠是這樣子的，還能夠有不少好比 @desc 描述之類的，你們能夠參考 jsDocgithub

代碼塊註釋

代碼塊註釋，也能夠說是方法註釋，能夠提現出方法的用處，已經所需參數，返回值等；大大提升代碼的可讀性！面試

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

/**
 * 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.<number>} 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)

相關文章
相關標籤/搜索
每日一句
    每一个你不满意的现在，都有一个你没有努力的曾经。
本站公眾號
   歡迎關注本站公眾號,獲取更多信息
聯繫我們 最近搜索 最新文章 沪ICP备13005482号-10 MyBatis教程 SQL 教程 MySQL教程 Java 教程 Thymeleaf 教程 Hibernate教程 Spring教程 Redis教程