选一个能完成的任务
配方面向已经能使用基本工具的读者。题目写成“从索引中取前 2 条记录”这类可完成的任务。开头给出起始状态和期望结果。较长的概念解释可以链接到文档类型与结构所描述的概念页。
先写一条能跑通的主路径。需要分支时,在相关步骤前说明适用的输入或平台。分支结果不同时,分别给出读者可以观察的结果。
提供可复制的输入与步骤
以下例子使用已安装 Node.js 的 POSIX Shell。输入是 3 条按搜索结果顺序排列的记录,输出是前 2 条记录的标题。将整段复制到终端运行。
node --input-type=module <<'NODE'
const entries = [
{ title: '生成索引' },
{ title: '配置输出路径' },
{ title: '验证搜索' },
]
for (const entry of entries.slice(0, 2)) {
console.log(entry.title)
}
NODE
验证结果并检查边界
终端应按输入顺序显示以下两行。
生成索引
配置输出路径
当输入少于 2 项时,示例返回全部已有项。可把数组改为只有一项,确认程序只打印该项。需要改变排序时,先按实际规则准备好输入,再按同一条路径核对结果。
在撰写真实配方时,为每个命令交代先前操作及路径要求。用代码示例检查验证从复制到结果的全过程。