技术英语 / 系统课时

让代码示例真正能说明问题

让代码示例真正能说明问题

技术文档里的代码示例不是装饰,也不是从项目中随手截取的一段实现。一个有效示例应该让读者复制后就能理解核心行为,并且代码中的上下文、输入、输出与正文描述保持一致,不需要读者自行补猜缺失条件。

学习目标

  • 选择能够证明核心行为的最小可运行示例
  • 保证示例的依赖、输入、执行方式和预期输出彼此一致
  • 删除与教学目标无关的真实项目细节,避免示例噪声掩盖重点

先确定示例究竟要证明什么

写代码前先用一句话定义目标,例如“证明 parseLimit 会把合法字符串转换成整数,并拒绝超出范围的值”。这句话决定了示例需要保留什么,也决定了哪些认证、日志、框架初始化和业务对象可以删除。

如果一个示例同时试图解释配置加载、网络请求、缓存、重试和结果解析,读者很难判断哪部分才是本节知识点。参考文档通常更适合展示一个最小行为,再通过正文说明它与真实项目的连接位置。

最小并不等于片段残缺。调用了某个变量,就必须说明它从哪里来;使用第三方包,就要给出依赖或导入方式;声称代码可直接运行,就不能把关键函数留成未定义状态。

用最小可运行示例锁定上下文

下面的示例只演示“解析并校验 limit 参数”,因此不引入 Web 框架或数据库。输入、入口和错误路径全部存在,可以直接保存为 JavaScript 文件运行。

js
function parseLimit(input) {
  const value = Number(input);

  // 只接受 1 到 100 的整数,避免隐式接受小数或越界值。
  if (!Number.isInteger(value) || value < 1 || value > 100) {
    throw new RangeError("limit must be an integer from 1 to 100");
  }

  return value;
}

console.log(parseLimit("20"));

try {
  parseLimit("200");
} catch (error) {
  console.log(error.message);
}

预期输出

text
20
limit must be an integer from 1 to 100

正文现在可以准确写成:parseLimit(input) 接受字符串或可转换为数字的输入,合法范围为 1 到 100;合法时返回整数,非法时抛出 RangeError。代码、输入和输出共同证明了这段说明。

让文字与代码逐项对得上

示例发布前,可以按“说明中的每个承诺是否都能在代码里找到证据”进行检查。如果正文说“默认值为 20”,示例却从未体现默认逻辑,读者会误以为缺少了一段代码;如果文字说函数返回字符串,而实际输出是数字,示例反而会削弱文档可信度。

同样要检查名字和取值是否一致。正文写 limit,代码就不要突然改成 pageSize;正文说最大值为 100,示例也不能继续使用旧版本的 500。复制旧示例后修改 API 名称,却忘记同步输出,是参考文档里最常见的失配之一。

删除真实项目中的无关细节

真实生产代码经常包含日志、监控、依赖注入、环境变量和兼容逻辑,但这些内容不一定属于示例。如果删除某段细节不会改变本节要证明的行为,就优先删除;如果删除后代码无法理解或无法运行,则保留最少的必要上下文。

反过来,也不要为了追求短小而省略关键前提。需要 Node.js 版本、环境变量或依赖包时,应在示例附近明确说明。不能独立运行的代码应明确标为片段示例,并指出它依赖哪个函数、对象或框架上下文。

一个好的代码示例最终应满足三个条件:读者知道从哪里开始运行,运行结果能够验证正文中的关键承诺,而且删除任何剩余代码都会让这个承诺更难理解。达到这三点,示例才真正承担了说明问题的作用。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

让代码示例真正能说明问题

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通