知识卡片

普通读书笔记卡 · 1875.e.2

文档贴近代码保留决策原因

理解等级:中级

把模块和导出接口说明保存在源码附近,并生成客户可读文档,可以降低两处信息分别维护的风险。内部注释应解释目的、工程取舍和放弃的替代方案;逐行复述实现会在修改时制造同步负担。贴近代码指共同维护真实知识,不代表所有设计背景都能从语法自动推导。

这张卡片看不懂?

已有反馈 · 0 条

    还没有人提交反馈。

    在整书笔记中的位置

    原书出处 · 1 处

    • 7 交流! · 查看原书依据

      把文档嵌进去,而不要栓在表面 用源码中的注释生成好看的文档非常容易,建议给模块和导出函数都加上注释,这能在其他开发者使用的时候,给他们很大的助力。 不过,有人说必须给每个函数、数据结构、类型声明等都分别加上注释,我们并不

    参考来源

    - 位置:《程序员修炼之道:通向务实的最高境界(第2版)》,`extracted/程序员修炼之道:通向务实的最高境界(第2版)/_epub-src/text/part0010_split_007.html`。 - 结论依据:本处实际展开的论点与例证;正文中的读者边界分析不冒充原书已提供的实现。 - 原始内容:把文档嵌进去,而不要栓在表面 用源码中的注释生成好看的文档非常容易,建议给模块和导出函数都加上注释,这能在其他开发者使用的时候,给他们很大的助力。 不过,有人说必须给每个函数、数据结构、类型声明等都分别加上注释,我们并不