44 lines
1.7 KiB
Markdown
44 lines
1.7 KiB
Markdown
# DOC-013 用可观察契约说明语义
|
|
|
|
分类：语义与边界。级别：核心。本规则是项目写作约定，不是语言语义。
|
|
|
|
## 规则
|
|
|
|
语法说明应明确输入、名称或类型约束、结果、依赖与相关阶段，而不止列关键字。
|
|
|
|
## 原因
|
|
|
|
读者需要理解写法意味着什么，系统实现也需要可核对的行为要求。
|
|
|
|
## 执行方法
|
|
|
|
1. 对函数说明参数、返回类型与结果；对组件说明参数与子节点约束。
|
|
2. 只有阶段差异影响理解时才专门说明 Preflight 与 inflight，避免每段重复阶段定义。
|
|
3. 区分算术结合、调用参数求值顺序和数据依赖；未定义的语义不由示例补出。
|
|
|
|
## 改写对照
|
|
|
|
问题写法：只写 function 后面跟名字与括号。
|
|
|
|
推荐做法：同时说明输入类型、返回值及依赖结果何时可被使用。
|
|
|
|
以上是说明写作差异的项目例子，不新增语言能力。
|
|
|
|
## 验收
|
|
|
|
- [ ] 语法、规则和示例结果相互一致。
|
|
- [ ] 有可检查的效果。
|
|
- [ ] 没有用底层机制替代语言契约。
|
|
|
|
## 具体应用
|
|
|
|
逐项说明形式、输入、结果、依赖、效果和必要的阶段边界；字段根据对象选择。use 应说明引用效果，不强填函数返回值；组件应说明子节点和排列。
|
|
|
|
详见[契约字段](../references/semantic-contracts.md)与[导入参考](../examples/EX-02.md)。
|
|
|
|
## 依据与边界
|
|
|
|
[SRC-02](../research/SRC-02.md)、[SRC-06](../research/SRC-06.md)。来源页记录观察与分析，本页的执行方法是针对项目的综合建议，不宣称由某一原文逐项规定。
|
|
|
|
[规则索引](../README.md#规则索引) · [检查清单](../checklist.md)
|