知识卡片

普通读书笔记卡 · 6075.a.3

文档解释语义避免重复签名

理解等级:高级

注释重复“参数是不可变引用”之类签名已有信息,维护成本高且容易在重构后出错。应写类型未表达的前提、边界与用途,例如包围盒相交只是精确碰撞的必要条件。也不要把远处调用者的当前文件与步骤写进接口契约;解释稳定理由更易长期维护。

这张卡片看不懂?

已有反馈 · 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