知识卡片

普通读书笔记卡 · 4545.g.11.w.11

从源码附近提取接口文档

理解等级:中级

把包、函数与接口的用途、输入输出和限制写在源码附近,再由工具提取展示,可以减少文档与实现分处维护的距离。Go文档工具把声明和相邻说明一起提供给读者。

提取只复制已有说明,不会理解并证明其语义正确。注释要解释契约与边界,而不只是重复函数名;源码变化后仍需同步更新描述。

这张卡片看不懂?

已有反馈 · 0 / 10 条

    还没有人提交反馈。

    在整书笔记中的位置

    原书出处 · 1 处

    • · 查看原书依据

      文档,更多的是指代码中的注释、函数、接口的输入、输出、 功能和参数说明,这些对于后续的维护和复用有着至关重要的作用。 在传统开发中,同步设计文档和代码是一件非常困难的事情。一旦开始有一些细微的不一致, 8 之后这个鸿沟将

    参考来源

    - 位置:《Go语言编程 完整版》第07章《工程管理》(来源项目book-sources:extracted/Go语言编程 完整版/_epub-src/text/part0000_split_003.html;spine 4,归一字符[6419,6529)) - 结论依据:原文从维护与复用需求引出源码注释提取,保留提取与语义维护的不同职责。 - 原始内容:文档,更多的是指代码中的注释、函数、接口的输入、输出、 功能和参数说明,这些对于后续的维护和复用有着至关重要的作用。 在传统开发中,同步设计文档和代码是一件非常困难的事情。一旦开始有一些细微的不一致, 8 之后这个鸿沟将