1
0
wiki/FormalSciences/ComputerScience/SoftwareEngineering/1.Collaboration/7.注释(Comments).md

88 lines
2.1 KiB
Markdown
Raw Permalink Normal View History

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