3.4 KiB
示例设计与验证
示例承担一个可检查的教学目标。完整性由这个目标需要的条件决定，不由代码行数决定。
先选择示例等级
| 等级 | 必须交代 | 合适的效果表述 |
|---|---|---|
| 概念或 key 示例 | 对象、组成、用于说明的区别 | “该 key 定位……” |
| 合法源码片段 | 所在位置、依赖声明、归属、语言状态 | “在这些条件下，预期……” |
| 完整逻辑代码视图 | 所有展示的声明与依赖、未定义的外部条件 | “这份视图描述……” |
| 实际执行示例 | 真实环境、调用方式、输入和取得的输出 | “在指定环境执行，得到……” |
本仓库的设计稿常用前三类。缺少运行入口不能靠命令名或启动步骤补造。源码围栏使用仓库约定的 endorphin；无效反例使用 text 并明确标为错误写法，避免复制后被误用。
建立一个实例的说明单
先确定单一目标，再列以下字段：归属 key；依赖 key 与声明；片段位置；输入；成功结果；为什么产生该结果；相关边界；验证方式。
例如跨 namespace 的定价例子中，归属是 market:shop.checkout，依赖是 atelier:shop.pricing。market 与 atelier 都是 workspace handle。discountedPrice 必须有声明依据，直接名称查找需有局部假设。输入 100 与 10 时，两次扣减得到 90 和 85。这个结果说明数据依赖，不证明远端执行顺序的全部规则。
说明单可放在作者工作记录中；成稿将字段融入自然段、代码和结果表，不要求每个例子都显示八项元数据。
控制新概念
第一例仅证明主要规则。第二例改变一个有意义的条件，例如从一层路径变为多层路径，或在已有计算结果上继续调用。只有当比较确实需要时才提供第三例。
“一个例子一个目标”不等于永远只有一个概念。调用必须使用函数、参数、结果；相关概念可通过已有声明和短链接提供，避免为了极简删掉必要条件。
选择反例
选择读者可能写出的错误，并紧邻关联规则。写清错误原因、出现阶段和最小修正。阶段尚未确定时不能强行归类。
有教学目的的错误代码要标明无效，并解释怎样修正。不能在正例前只放一个警告、正文仍沿用错误写法。工具用于正例约定检查时，应允许明确标注的反例存在于专门的 text 围栏。
保持业务对象连续
沿用商品与定价背景有助于减少额外解释。改变名字或数值时核对全文引用和手算结果；引入新领域应服务读者任务。官方组件、用户库、业务数据 id、namespace key 各自承担不同角色。
验证顺序
先核对关键断言依据，再逐个解析名称和前提，然后计算结果或描述 UI 效果，最后核查代码与文字一致。
用户明确要求执行验证时，才在对应环境运行程序；平时记录“按文档规则推演”。数值通过其他语言计算出相同结果也不能证明 Endorphin 源码运行通过。
检查代表性输入之外，再选一个能暴露解释错误的输入。定价例子可把输入换为 80 与 7，预期依次为 73 和 68；不要把这个补充输入自动扩展为负数、溢出、所有整数都已定义。