44 lines
1.6 KiB
Markdown
44 lines
1.6 KiB
Markdown
# DOC-009 最小示例必须有完整条件
|
|
|
|
分类：示例与教学。级别：核心。本规则是项目写作约定，不是语言语义。
|
|
|
|
## 规则
|
|
|
|
示例尽量小，但不能靠省略必要条件缩短；明确它是完整声明、局部片段还是提案示意。
|
|
|
|
## 原因
|
|
|
|
读者需要知道代码如何放置，而不是只看到一段外观正确的符号。
|
|
|
|
## 执行方法
|
|
|
|
1. 去掉与本节目标无关的配置，保留必要声明与输入。
|
|
2. 局部名称来自参数或前文时明确说明；不同外部 key 的代码分开标记。
|
|
3. 未定能力使用说明而非补写虚构实现；复制执行的承诺只对经过真实验证的例子作出。
|
|
|
|
## 改写对照
|
|
|
|
问题写法：把 use 与顶层 let 混成一份所谓完整程序。
|
|
|
|
推荐做法：完整函数展示 use 与函数体；查询片段注明 let 位于函数体内。
|
|
|
|
以上是说明写作差异的项目例子，不新增语言能力。
|
|
|
|
## 验收
|
|
|
|
- [ ] 所有必要条件可查。
|
|
- [ ] 占位符没有冒充实际 API。
|
|
- [ ] 示例标签与验证等级一致。
|
|
|
|
## 具体应用
|
|
|
|
先选择概念、源码片段、逻辑视图或实际执行等级，再填写归属、位置和依赖条件。最小示例可以很短，但其中每个名称都需要声明或明确假设。
|
|
|
|
详见[示例等级](../references/example-design.md)与[完整上下文](../examples/EX-03.md)。
|
|
|
|
## 依据与边界
|
|
|
|
[SRC-04](../research/SRC-04.md)、[SRC-08](../research/SRC-08.md)。来源页记录观察与分析，本页的执行方法是针对项目的综合建议，不宣称由某一原文逐项规定。
|
|
|
|
[规则索引](../README.md#规则索引) · [检查清单](../checklist.md)
|