知识卡片

普通读书笔记卡 · 2294.a.1.d

简短文档与文档第一定律

理解等级:中级

“可以工作的软件优先于详尽的文档”并不是不要文档。没有文档的软件是灾难,只读代码难以理解系统的原理和结构;但文档太多更可怕:编写和与代码保持同步都耗时,一旦不同步,文档就变成误导人的“谎言”。

作者给出的折中是:只维护一份短小精悍的原理与结构文档,最多一二十页,只讨论总体设计原理和最高层结构。新成员的培训靠紧密协作和手把手指导;向新人传递信息最好的两种“文档”是代码和团队:代码不会撒谎、没有歧义,但不易看出意图;系统不断变化的路线图在团队成员脑中,通过人与人互动传授最快。

由此得到“Martin 文档第一定律”:除非有迫在眉睫且重大的需求,否则不要写文档。“一二十页”是作者的经验尺度,应理解为“只写会长期稳定的高层原理”,而非精确页数要求。

这张卡片看不懂?

已有反馈 · 0 / 10 条

    还没有人提交反馈。

    在整书笔记中的位置

    原书出处 · 1 处

    参考来源

    - 位置:《敏捷开发(纪念版)》第01章《第1章 敏捷实践》可以工作的软件优先于详尽的文档(源文件:extracted/敏捷开发(纪念版)/_epub-src/Min Jie Kai Fa (Ji Nian Ban )_split_010.html,来源项目 book-sources) - 结论依据:原文先肯定无文档是灾难,再指出文档过多难以同步会变成谎言,主张只写简短的原理与结构文档,以代码和团队作为最好的文档,并提出 Martin 文档第一定律。 - 原始内容:除非有迫在眉睫且重大的需求,否则不要写文档。