1.4 KiB
1.4 KiB
DOC-004 显式交代前置知识与上下文
分类：读者与定位。级别：核心。本规则是项目写作约定，不是语言语义。
规则
示例和任务中的必要前提必须在使用点可见，不能依赖读者猜测。
原因
上下文遗漏会使正确的片段看起来像独立程序，也会把尚未定义的能力伪装成默认规则。
执行方法
- 标明外部归属、声明或片段类型；若名称来自前文，给出定位链接。
- 在跳转读者需要的地方重述最小前提，而不是复制整章。
- 未定的入口、官方导入或成员声明使用局部短注；没有实际环境时不承诺可运行。
改写对照
问题写法：直接给出 Product.get(id)，不说明 Product 和 get 的来源。
推荐做法：注明 Product 的定义位置，以及 get 是尚未确定的读取提案。
以上是说明写作差异的项目例子，不新增语言能力。
验收
- 片段使用位置明确。
- 涉及的名称有声明、前提或明确占位说明。
- 没有虚构安装命令或运行入口。