wiki/org/Git 协作规范/注释（Comments）.md

id	title	sidebar_position	data
注释（Comments）	注释（Comments）	1.5	2022年7月11日

规范

代码就是最好的注释，尽量使用英文注释，坚决不滥用注释。不需要标明作者、时间、改动记录，请把这些放在 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');