Files
Endorphin-Document/authoring/tasks/TASK-04.md
T

2.2 KiB

TASK-04 新增与修复示例

适用:补充例子、统一例子风格、修复过时写法、解释结果,或检查示例是否表达了错误语义。

必读:示例设计、DOC-009、DOC-010、DOC-011、DOC-012、DOC-015。

盘点已有例子

先搜索代码围栏及相关名称,再阅读文字条件。盘点对象包括正文、文法说明、表格中的短例子和手册中的示范;不要只查 endorphin 围栏。

将命中项分成正例、明确无效的反例、形式文法、来源原样名称和历史记录。修复错误时只改需要同步的类别;有意反例应继续展示错误及原因。

设计最小完整例子

确定读者目标与示例等级。为目标准备最少的声明和输入,明确代码归属。跨 namespace 示例分别写出提供方和使用方归属,避免读者把 use 的目标当作当前归属。

每个名称都能回到声明或局部假设。省略依赖时说明省略什么和为何可省略;尚未定义的官方引用不能被用户库导入掩盖。

解释结果

数值给输入、结果和关键中间值;UI 给可见内容、排列及必要前提;身份/key 给对象之间相同或不同的关系。

“代码很清晰”不替代解释。说明为什么第二次调用依赖第一次结果,比逐行说“这里调用函数”更有价值。已有规则无法决定结果时,说明缺少的条件。

修复时的联动

改变函数签名要检查调用点和返回说明;改变名字要检查代码外叙述;改变输入要重算所有结果;改变归属要检查 use;改变状态要同步局部提案说明与规范状态。

不把修复示例当成设计新能力的机会。改用一个已定义的更小例子,通常优于虚构构造器、导入路径或数据接口。

验收

按文档规则逐步推演,并选一个针对性变化检验解释是否仍成立。只有用户明确要求执行代码时才运行相关工具。交付区分手算、人工结构核对和实际执行。

完整多 namespace 示例及其验收见EX-03。

任务入口