知识卡片
简短文档与文档第一定律
“可以工作的软件优先于详尽的文档”并不是不要文档。没有文档的软件是灾难,只读代码难以理解系统的原理和结构;但文档太多更可怕:编写和与代码保持同步都耗时,一旦不同步,文档就变成误导人的“谎言”。
作者给出的折中是:只维护一份短小精悍的原理与结构文档,最多一二十页,只讨论总体设计原理和最高层结构。新成员的培训靠紧密协作和手把手指导;向新人传递信息最好的两种“文档”是代码和团队:代码不会撒谎、没有歧义,但不易看出意图;系统不断变化的路线图在团队成员脑中,通过人与人互动传授最快。
由此得到“Martin 文档第一定律”:除非有迫在眉睫且重大的需求,否则不要写文档。“一二十页”是作者的经验尺度,应理解为“只写会长期稳定的高层原理”,而非精确页数要求。
这张卡片看不懂?
这张卡片已通过人工审查,不再接受失败反馈。
已有反馈 · 0 条
还没有人提交反馈。
在整书笔记中的位置
- · 第1章 敏捷实践
原书出处 · 1 处
- 第1章 敏捷实践 · 查看原书依据
除非有迫在眉睫且重大的需求,否则不要写文档。
参考来源
- 位置:《敏捷开发(纪念版)》第01章《第1章 敏捷实践》可以工作的软件优先于详尽的文档(源文件:extracted/敏捷开发(纪念版)/_epub-src/Min Jie Kai Fa (Ji Nian Ban )_split_010.html,来源项目 book-sources)
- 结论依据:原文先肯定无文档是灾难,再指出文档过多难以同步会变成谎言,主张只写简短的原理与结构文档,以代码和团队作为最好的文档,并提出 Martin 文档第一定律。
- 原始内容:除非有迫在眉睫且重大的需求,否则不要写文档。