知识卡片
文档解释语义避免重复签名
注释重复“参数是不可变引用”之类签名已有信息,维护成本高且容易在重构后出错。应写类型未表达的前提、边界与用途,例如包围盒相交只是精确碰撞的必要条件。也不要把远处调用者的当前文件与步骤写进接口契约;解释稳定理由更易长期维护。
这张卡片看不懂?
这张卡片的反馈已满 10 条,暂时无法继续提交。
已有反馈 · 0 / 10 条
还没有人提交反馈。
在整书笔记中的位置
原书出处 · 1 处
- Chapter 5. Tooling What Not to Document · 查看原书依据
avoid repeating in text something that’s clear from the code. Item 1 exhorted you to encode as much semantics as possible into Rust’s type system; once you’ve done that, allow the type system to document those semantics. Assume that the reader is familiar with Rust—possibly because they’ve read a helpful collection of Items describing effective use of the la
参考来源
- 位置:《Effective Rust 35 Specific Ways to Improve Your Rust Code (David Drysdale)》第5章《What Not to Document》(spine9;extracted/Effective Rust 35 Specific Ways to Improve Your Rust Code (David Drysdale)/_epub-src/OEBPS/ch05.html;u138-ch05-005)。
- 结论依据:原文在“avoid repeating in text”附近的定义、例子或代码支撑本卡核心说明:注释重复“参数是不可变引用”之类签名已有信息,维护成本高且容易在重构后出错。边界按已读前提解释;示例未执行。
- 原始内容:avoid repeating in text something that’s clear from the code. Item 1 exhorted you to encode as much semantics as possible into Rust’s type system; once you’ve done that, allow the type system to document those semantics. Assume that the reader is familiar with Rust—possibly because they’ve read a helpful collection of Items describing effective use of the la