知识卡片
从源码附近提取接口文档
把包、函数与接口的用途、输入输出和限制写在源码附近,再由工具提取展示,可以减少文档与实现分处维护的距离。Go文档工具把声明和相邻说明一起提供给读者。
提取只复制已有说明,不会理解并证明其语义正确。注释要解释契约与边界,而不只是重复函数名;源码变化后仍需同步更新描述。
这张卡片看不懂?
这张卡片已通过人工审查,不再接受失败反馈。
已有反馈 · 0 条
还没有人提交反馈。
在整书笔记中的位置
原书出处 · 1 处
- · 查看原书依据
文档,更多的是指代码中的注释、函数、接口的输入、输出、 功能和参数说明,这些对于后续的维护和复用有着至关重要的作用。 在传统开发中,同步设计文档和代码是一件非常困难的事情。一旦开始有一些细微的不一致, 8 之后这个鸿沟将
参考来源
- 位置:《Go语言编程 完整版》第07章《工程管理》(来源项目book-sources:extracted/Go语言编程 完整版/_epub-src/text/part0000_split_003.html;spine 4,归一字符[6419,6529))
- 结论依据:原文从维护与复用需求引出源码注释提取,保留提取与语义维护的不同职责。
- 原始内容:文档,更多的是指代码中的注释、函数、接口的输入、输出、 功能和参数说明,这些对于后续的维护和复用有着至关重要的作用。 在传统开发中,同步设计文档和代码是一件非常困难的事情。一旦开始有一些细微的不一致, 8 之后这个鸿沟将