知识卡片

普通读书笔记卡 · 1232.b.6

文档的价值与篇幅成反比

理解等级:中级

好文档对项目必不可少,没有它团队会迷失在代码的海洋里;但充满错误的文档更糟,读者被误导后仍然迷失。所以文档必须写,但要慎重选择写什么:复杂的通信协议、复杂的关系模型、复杂的可重用框架需要文档,但它们都不需要数百页的 UML 图。软件文档应简明扼要,其价值与篇幅成反比。

作者的经验尺度是:一个 12 人团队维护百万行代码,需要长期保存的文档总量控制在 25–200 页,越少越好,内容包括重要模块高层结构的 UML 图、关系模型的 ER 图、一两页的构建说明、测试指南和源码控制说明等,放在 wiki 或协作写作工具里,方便所有人浏览、搜索和修改。把文档变小变薄需要大量工作,但值得,因为人们会读小文档,不会读上千页的大部头。

第14章的总结是:UML 是工具而不是最终结果,少量使用收益巨大,过度使用浪费大量时间,使用 UML 时少即是好。

这张卡片看不懂?

已有反馈 · 0 / 10 条

    还没有人提交反馈。

    在整书笔记中的位置

    原书出处 · 1 处

    • 第14章 使用UML · 查看原书依据

      文档必须得写,但必须得慎重写。哪些不需要文档和哪些需要文档,选择很重要。复杂的通信协议需要文档。复杂的关系模型需要文档。复杂的可重用框架需要文档。

    参考来源

    - 位置:《敏捷开发(纪念版)》第14章《第14章 使用UML》那么,文档呢;小结(源文件:extracted/敏捷开发(纪念版)/_epub-src/Min Jie Kai Fa (Ji Nian Ban )_split_024.html,来源项目 book-sources) - 结论依据:原文说明好文档必要、错误文档更糟,列出需要文档的对象,提出文档价值与篇幅成反比,给出 12 人百万行代码项目保留 25–200 页文档的经验及其内容与存放方式;小结强调 UML 是工具、少即是好。 - 原始内容:文档必须得写,但必须得慎重写。哪些不需要文档和哪些需要文档,选择很重要。复杂的通信协议需要文档。复杂的关系模型需要文档。复杂的可重用框架需要文档。