Files
Endorphin-Document/authoring/examples/EX-04.md
T

2.2 KiB

EX-04 写出可以直接实施的审查意见

读者目标:区分确定的文档缺陷与需要确认的语言设计。下列原稿是用于审稿训练的合成材料,不是语言规范。

待审原稿

class 声明会自动创建数据库表。任何类都可以直接调用 get;数据不存在时得到空对象。use 会授权调用目标 namespace 的全部函数,所以只要知道用户名就可以读取数据。这些例子都已通过运行测试。

只提供这段文字,没有执行记录,也没有新的语言决定。

审查发现示范

优先级 位置与断言 依据和读者影响 最小修正
阻断 “自动创建数据库表” 类型结构被写成持久化规则,超出当前规范范围 删除自动建表主张,说明 class 表达结构
阻断 “任何类都可以直接调用 get” 读取例子中的成员假设被扩大为内置 API 恢复 Product.get 提案及成员声明未定说明
阻断 “不存在时得到空对象” 未定义的缺失处理被伪装成成功值 说明缺失须可观察,类型与处理形式仍待定义
阻断 “use 会授权” key 定位与访问授权被混为一谈 明确 use 指定依赖,授权另行决定
阻断 “已通过运行测试” 没有测试环境与执行证据 改为实际完成的验证等级,未执行则明确未执行

依据分别来自类型、数据读取、身份、程序结构和规范状态的主定义。正式报告应给出对应文件与位置,避免仅写“违反本手册”。

不应额外下的结论

不能因为 get 尚未定义,就决定采用新的 query 关键字;不能因为授权未定,就补一套权限装饰器;也不能把“作者更喜欢另一种标题”列为阻断。

若用户只要求审查

交付上述问题及修正建议,保留原文件。若用户要求修复,依据已确定范围落实文字并核对相关例子,最后只列仍需决定的部分。

验收

另一作者应能根据报告找到原句、理解错误影响并完成最小修正。没有代码执行或真实用户参与时,不声称经过运行或用户测试。

对应任务 · 示例目录