44 lines
1.7 KiB
Markdown
44 lines
1.7 KiB
Markdown
# DOC-004 显式交代前置知识与上下文
|
|
|
|
分类：读者与定位。级别：核心。本规则是项目写作约定，不是语言语义。
|
|
|
|
## 规则
|
|
|
|
示例和任务中的必要前提必须在使用点可见，不能依赖读者猜测。
|
|
|
|
## 原因
|
|
|
|
上下文遗漏会使正确的片段看起来像独立程序，也会把尚未定义的能力伪装成默认规则。
|
|
|
|
## 执行方法
|
|
|
|
1. 标明外部归属、声明或片段类型；若名称来自前文，给出定位链接。
|
|
2. 在跳转读者需要的地方重述最小前提，而不是复制整章。
|
|
3. 未定的入口、官方导入或成员声明使用局部短注；没有实际环境时不承诺可运行。
|
|
|
|
## 改写对照
|
|
|
|
问题写法：直接给出 Product.get(id)，不说明 Product 和 get 的来源。
|
|
|
|
推荐做法：注明 Product 的定义位置，以及 get 是尚未确定的读取提案。
|
|
|
|
以上是说明写作差异的项目例子，不新增语言能力。
|
|
|
|
## 验收
|
|
|
|
- [ ] 片段使用位置明确。
|
|
- [ ] 涉及的名称有声明、前提或明确占位说明。
|
|
- [ ] 没有虚构安装命令或运行入口。
|
|
|
|
## 具体应用
|
|
|
|
从例子里的每个名称倒查所需声明与概念，将影响合法性的条件放到使用点。全书已经介绍的背景可以短链接，直接跳入仍须看见局部假设。
|
|
|
|
详见[示例条件](../references/example-design.md)与[调用示范](../examples/EX-03.md)。
|
|
|
|
## 依据与边界
|
|
|
|
[SRC-04](../research/SRC-04.md)、[SRC-15](../research/SRC-15.md)。来源页记录观察与分析，本页的执行方法是针对项目的综合建议，不宣称由某一原文逐项规定。
|
|
|
|
[规则索引](../README.md#规则索引) · [检查清单](../checklist.md)
|