88 lines
2.1 KiB
Markdown
88 lines
2.1 KiB
Markdown
---
|
||
title: 注释（Comments）
|
||
description: 本文规定了代码注释的格式，包括行注释、关键字注释和版权注释的写法，强调注释应清晰、准确并位于适当位置。
|
||
keywords:
|
||
- 代码注释
|
||
- 版权
|
||
- 关键字
|
||
- 格式规范
|
||
tags:
|
||
- FormalSciences/ComputerScience
|
||
- SoftwareEngineering/Collaboration
|
||
- Git
|
||
author: 7Wate
|
||
date: 2023-06-26
|
||
---
|
||
|
||
**代码**应视为**最好的注释**，因此应尽量使用**英文注释**，并坚决**避免滥用**注释。不必在代码中标明**作者、时间、或改动记录**，这些信息应放在 **Git** 的**提交日志**中！
|
||
|
||
## 行注释
|
||
|
||
行注释应放在相应代码行**之前**，而不是代码行之后。
|
||
|
||
```javascript
|
||
// 注释文字
|
||
代码
|
||
```
|
||
|
||
示例：
|
||
|
||
```javascript
|
||
// 启用便携式支持
|
||
const portable = bootstrapNode.configurePortable(product);
|
||
```
|
||
|
||
## 关键字注释
|
||
|
||
在注释块的**尾部**，关键字前添加 `@` 符号。
|
||
|
||
```javascript
|
||
/*
|
||
* 注释
|
||
* @type{变量} 注释
|
||
* @param{变量} 注释
|
||
* @returns{变量} 注释
|
||
*/
|
||
```
|
||
|
||
示例：
|
||
|
||
```javascript
|
||
/*
|
||
* @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));
|
||
});
|
||
}
|
||
```
|
||
|
||
## 版权注释
|
||
|
||
版权注释应位于**代码文件首行**。
|
||
|
||
```javascript
|
||
/*----------------
|
||
* 版权归 XX 所有
|
||
* 遵循 XX 开源协议
|
||
*----------------*/
|
||
|
||
代码···
|
||
```
|
||
|
||
上下分割线的长度应为描述文字长度的 1.1 倍。`/* */` 不应与注释内容放在同一行，且描述文字前应保持 1 个空格。
|
||
|
||
示例：
|
||
|
||
```javascript
|
||
/*---------------------------------------------------------------------------------------
|
||
* 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');
|
||
```
|