文档规范

代码规范

本文特指撰写 Markdown 文档时的代码规范。

# 1 行内代码

行内代码使用反引号包裹。

`code`

code

提示

如果代码中包含反引号，使用两个反引号包裹，以此类推。

`` `code` ``

`code`

提示

如果代码中没有出现成对的反引号，可以使用 <code> 标签包裹。

<code>`</code>

需要包裹的行内代码包括：JS 中的变量、字面量、运算符、关键字、函数，HTML 中的标签，输入、输出，文件名等。
- 字符串需要使用引号，防止混淆，如：
  typeof 1 返回 "number"。
- HTML 标签推荐使用尖括号包裹，如 <span> 标签。
英文单词、专有名词不要包裹，如：

事件传播的三个阶段是 capture、target、bubble。
对于数字：如果代表数字字面量或输出，需要包裹；如果代表数量，不需要包裹。如：

1 s 后，代码会输出 1。
对于 Set、Map 等数据结构，如果泛指名称，不需要包裹；如果指代具体的类或实例，需要包裹。如：

Set 集合是一种数据结构，它的成员是唯一的。

将数组转为 Set 集合时，集合会自动去重。
对于 JS 中的数据类型，一般用小写形式并包裹，如：

单目运算符 + 可将后面的变量/字面量转换为 number 类型（等同于 Number() 函数）。
行内代码需要用到空格、缩进时，参考代码块的规范。

# 2 键盘按钮

键盘按钮使用 <kbd> 标签包裹。

<kbd>Ctrl</kbd> + <kbd>C</kbd>

Ctrl + C

用 + 连接多个键盘按钮，两侧各留一个空格，且不要使用行内代码或 <kbd> 标签包裹。

# 3 代码块

代码块使用三个反引号包裹。

```javascript
console.log('Hello World!')
```

1
2
3

console.log('Hello World!')

提示

如果代码中包含三个反引号，使用四个反引号包裹，以此类推。

````markdown
```javascript
console.log('Hello World!')
```
````

1
2
3
4
5

```javascript
console.log('Hello World!')
```

1
2
3

# 3.1 空格与缩进

JS、TS、HTML、CSS 均使用 2 个空格缩进，不要使用 4 个空格或 Tab 缩进。
JS、TS 运算符前后各留一个空格，如：
```
const a = 1 + 2;
```
1
JS、TS 对于一些非运算符的符号，视情况而定：
- 逗号、冒号、分号前不留空格，后留一个空格，如：
```
const arr = [1, 2, 3];
const obj = { a: 1, b: 2 };
```
  1
  2
```
const a: number = 1;
```
  1
- 箭头函数的箭头 => 前后各留一个空格，如：
```
const fn = (a, b) => a + b;
```
  1
- 扩展运算符 ... 前后不留空格，如：
```
const arr = [1, 2, 3];
const arr2 = [...arr];
```
  1
  2
JS、TS 关键字与左括号之间需要留一个空格，如：
```
if (a > 0) {
  console.log('a > 0');
}
```
1
2
3
JS、TS 函数定义和调用时，函数名与左括号之间不需要留空格，如：
```
function add(a, b) {
  return a + b;
}

add(1, 2);
```
1
2
3
4
5
JS、TS 对函数表达式和匿名函数，function 关键字与左括号之间需要留空格，如：
```
const add = function (a, b) {
  return a + b;
};
```
1
2
3

JS、TS 对于生成器函数，统一使用以下的写法：

function* gen() { yield 1; }  // 函数声明
const gen2 = function* () { yield 2; }; // 函数表达式
const obj = {
  *gen3() { yield 3; }
};  // 对象方法

1
2
3
4
5

JS、TS 当把函数或对象写成一行时，大括号与内容之间需要留一个空格，如：
```
const obj = { a: 1, b: 2 };
const fn = function () { console.log('Hello World!'); };
```
1
2

# 3.2 JS、TS 语句规范

语句结尾一般使用分号。无论是否使用分号，整个代码块需要保持一致。
语句块使用大括号包裹，即使只有一条语句。
左大括号应与语句同行且前面添加空格，右大括号应单独一行。
```
if (a > 0) {
  console.log('a > 0');
} else {
  console.log('a <= 0');
}
```
1
2
3
4
5

# 3.3 展示规范

文档中的代码块一般是展示范例用的，因此代码应该是可以直接运行的，不要出现语法错误。代码展示前必须运行一遍。

对单独的 JS、TS 代码，使用 Markdown 代码块展示，并在恰当位置添加注释。

如果代码有输出结果或有报错，应添加注释，如：

console.log(typeof 1);  // number
console.log(typeof '1');  // string
console.log(typeof true);  // boolean

1
2
3

如果代码是异步输出，或输出与代码顺序不一致，应在最后一行添加输出结果，或单独使用一个无语言的代码块展示输出结果，如：

async function getData() {
  console.log(1);
  const p = await Promise.resolve("I made it!");
  console.log(2);
  return p;
}

const data = getData();
console.log(3);
data.then(res => console.log(res));
console.log(4);
// 输出顺序：1 => 3 => 4 => 2 => I made it!

1
2
3
4
5
6
7
8
9
10
11
12

对 HTML 和 CSS 代码，如果只起到说明作用，应使用 Markdown 代码块展示，如：
```
<div class="container">
  <div class="item">1</div>
  <div class="item">2</div>
  <div class="item">3</div>
</div>
```
1
2
3
4
5
如果需要展示效果，应使用 CodePen (opens new window) 或 JSFiddle (opens new window) 等在线代码编辑器，如：
See the Pen <a href="https://codepen.io/kaluojushi/pen/QWrXpEZ"> CSSTriangleTest2</a> by Carlo (<a href="https://codepen.io/kaluojushi">@kaluojushi</a>) on <a href="https://codepen.io">CodePen</a>.
对 DOM 操作代码，按需使用 Markdown 代码块或 CodePen 等在线代码编辑器。

# 参考资料

在 GitHub 中编辑此页

上次更新于: 2022/10/25 00:52:37

← 中文排版规范 Markdown 规范→