# 注释（Comments）

2023年6月26日2分钟阅读

- FormalSciences/ComputerScience
- SoftwareEngineering/Collaboration
- Git

代码应视为最好的注释，因此应尽量使用英文注释，并坚决避免滥用注释。不必在代码中标明作者、时间、或改动记录，这些信息应放在 Git 的提交日志中！

## 行注释

行注释应放在相应代码行之前，而不是代码行之后。

    // 注释文字
    代码

示例：

    // 启用便携式支持
    const portable = bootstrapNode.configurePortable(product);

## 关键字注释

在注释块的尾部，关键字前添加 `@` 符号。

    /*
     * 注释
     * @type{变量} 注释
     * @param{变量} 注释
     * @returns{变量} 注释
     */

示例：

    /*
     * @param {string} dir
     * @returns {Promise<string>}
     */
    function mkdirp(dir) {
     return new Promise((resolve, reject) => {
      fs.mkdir(dir, { recursive: true }, err => (err && err.code !== 'EEXIST') ? reject(err) : resolve(dir));
     });
    }

## 版权注释

版权注释应位于代码文件首行。

    /*----------------
     * 版权归 XX 所有
     * 遵循 XX 开源协议
     *----------------*/

    代码···

上下分割线的长度应为描述文字长度的 1.1 倍。`/* */` 不应与注释内容放在同一行，且描述文字前应保持 1 个空格。

示例：

    /*---------------------------------------------------------------------------------------
     * Copyright (c) Microsoft Corporation. All rights reserved.
     * Licensed under the MIT License. See License.txt in the project root for license information.
     *---------------------------------------------------------------------------------------*/

    const perf = require('./vs/base/common/performance');
    perf.mark('code/didStartMain');