知识卡片

普通读书笔记卡 · 6075.a

接口文档补足类型未表达的契约

理解等级:中级

公开接口文档应说明用途、前提、错误、panic与unsafe要求,尤其是签名无法表达的限制。为标识符加代码样式与交叉链接,并在用法不明显时提供小示例。可测试示例有助保持同步,但文档是否有用仍取决于解释的契约是否完整。

这张卡片看不懂?

已有反馈 · 0 条

    还没有人提交反馈。

    在整书笔记中的位置

    原书出处 · 1 处

    • Chapter 5. Tooling Item 27: Document public interfaces · 查看原书依据

      Document public interfaces If your crate is going to be used by other programmers, then it’s a good idea to add documentation for its contents, particularly its public API. If your crate is more than just ephemeral, throwaway code, then that “other programmer” includes the you-of-the-future, when you have forgotten the details of your current code. This is n

    参考来源

    - 位置:《Effective Rust 35 Specific Ways to Improve Your Rust Code (David Drysdale)》第5章《Item 27: Document public interfaces》(spine9;extracted/Effective Rust 35 Specific Ways to Improve Your Rust Code (David Drysdale)/_epub-src/OEBPS/ch05.html;u134-ch05-001)。 - 结论依据:原文在“Document public interfaces”附近的定义、例子或代码支撑本卡核心说明:公开接口文档应说明用途、前提、错误、panic与unsafe要求,尤其是签名无法表达的限制。边界按已读前提解释;示例未执行。 - 原始内容:Document public interfaces If your crate is going to be used by other programmers, then it’s a good idea to add documentation for its contents, particularly its public API. If your crate is more than just ephemeral, throwaway code, then that “other programmer” includes the you-of-the-future, when you have forgotten the details of your current code. This is n