知识卡片
文档贴近代码保留决策原因
把模块和导出接口说明保存在源码附近,并生成客户可读文档,可以降低两处信息分别维护的风险。内部注释应解释目的、工程取舍和放弃的替代方案;逐行复述实现会在修改时制造同步负担。贴近代码指共同维护真实知识,不代表所有设计背景都能从语法自动推导。
这张卡片看不懂?
这张卡片已通过人工审查,不再接受失败反馈。
已有反馈 · 0 条
还没有人提交反馈。
在整书笔记中的位置
原书出处 · 1 处
- 7 交流! · 查看原书依据
把文档嵌进去,而不要栓在表面 用源码中的注释生成好看的文档非常容易,建议给模块和导出函数都加上注释,这能在其他开发者使用的时候,给他们很大的助力。 不过,有人说必须给每个函数、数据结构、类型声明等都分别加上注释,我们并不
参考来源
- 位置:《程序员修炼之道:通向务实的最高境界(第2版)》,`extracted/程序员修炼之道:通向务实的最高境界(第2版)/_epub-src/text/part0010_split_007.html`。
- 结论依据:本处实际展开的论点与例证;正文中的读者边界分析不冒充原书已提供的实现。
- 原始内容:把文档嵌进去,而不要栓在表面 用源码中的注释生成好看的文档非常容易,建议给模块和导出函数都加上注释,这能在其他开发者使用的时候,给他们很大的助力。 不过,有人说必须给每个函数、数据结构、类型声明等都分别加上注释,我们并不