Node.js 项目文档编写规范详解

Node.js 项目文档编写规范详解

node Node.js JavaScript runtime ✨🐢🚀✨ 项目地址: https://gitcode.com/gh_mirrors/no/node

前言

在开源项目中，高质量的文档与代码本身同等重要。Node.js 作为流行的 JavaScript 运行时环境，其文档体系直接影响着数百万开发者的使用体验。本文将深入解读 Node.js 项目的文档编写规范，帮助开发者理解如何为 Node.js 贡献专业、一致的文档内容。

文档基础规范

文件命名约定

• 使用小写字母和连字符组合（如 example-file.md）
• 特殊情况下允许使用下划线（如 child_process.md）
• 顶级文档文件可例外处理

文本排版要求

• 每行建议不超过 120 个字符
• 遵循 .editorconfig 中的格式配置
• 推荐安装编辑器插件自动执行格式规则

文档测试验证

提交文档变更前应执行测试：

make test-doc -j

或 Windows 环境下：

vcbuild test-doc

写作风格指南

语言规范

• 采用美式英语拼写（如 "color" 而非 "colour"）
• 使用简洁明了的表达，避免技术黑话
• 推荐使用牛津逗号（序列逗号）增强可读性

人称使用

• 避免第一人称（我/我们）
• 例外情况：可用 "we recommend" 替代被动语态

性别中立表达

推荐用语：

• they/their/them
• folks/people/developers

避免用语：

• his/hers/him/her
• guys/dudes

术语规范

• 使用准确的技术术语
• 首次出现的专业术语或缩写需提供解释

文档结构组织

标题层级

• 一级标题 # 作为文档开头
• 按内容层次使用 ##, ### 等子标题

链接格式

优先使用引用式链接：

详见[示例链接][]

[示例链接]: http://example.com

列表规范

• 无序列表使用 * 或 -
• 有序列表使用数字编号
• 保持列表项结构平行

表格使用

• 用于展示结构化数据
• 确保纯文本环境下可读

API 文档编写要点

YAML 注释更新

• 新增或弃用 API 时同步更新 YAML 注释

使用示例

• 每个函数都应提供示例代码或示例链接

参数描述格式

标准参数描述模板：

* `参数名` {类型} 描述文字。**默认值:** `默认值`

返回值描述模板：

* 返回: {类型} 描述文字

代码块规范

语法高亮标识

使用语言标识的代码块：

```js
// JavaScript 代码
```

支持的语言标识符包括：

| 语言 | 标识符 | |--------------|-------------| | JavaScript | js | | TypeScript | typescript| | Bash | bash | | JSON | json | | HTTP | http | | 终端会话 | console |

代码注释

• 在复杂逻辑处添加解释性注释
• 遵循对应语言的注释风格

格式细节规范

特殊字符转义

需转义的字符：

• 下划线 \_
• 星号 \*
• 反引号 \`

命名约定

• 构造函数：PascalCase
• 实例对象：camelCase
• 方法调用：带括号形式如 socket.end()

专有名词规范

产品名称

• 正确：JavaScript、Google's V8
• 错误：Javascript、Google's v8

Node.js 称谓

• 正式名称：Node.js
• 可执行文件：node

版本号引用

正确格式：

• Node.js 14.x
• Node.js 16.15.1

错误格式：

• Node.js v14

结语

遵循这些规范能确保 Node.js 文档保持专业性和一致性。对于未涵盖的特殊情况，可参考微软写作风格指南作为补充。良好的文档是项目成功的关键因素，期待您为 Node.js 社区贡献优质的文档内容。

node Node.js JavaScript runtime ✨🐢🚀✨ 项目地址: https://gitcode.com/gh_mirrors/no/node