知识卡片

普通读书笔记卡 · 4651.d.2

辅助设计文档的两种用途

理解等级:中级

源码是设计,但并非唯一要产出的文档。除用户手册、安装指南等外,辅助设计文档有两个重要用途:

  1. 捕获问题域信息:建模时需要理解问题域,其中有些信息最终不会直接建模进软件,但能帮助设计者判断什么是本质概念、如何建模最好,应该记录下来以备将来修改。
  2. 记录难以从设计本身提取的内容:无论高层还是低层,这类内容往往最适合用图形表达,难以写成代码注释——就像硬件学科用文字补充图形化设计文档一样。

使用原则:

  • 绝不要忘记由源码决定设计的真实样子,而不是辅助文档;
  • 手工保持这类文档更新很难,所以应保持最小化,并尽量在项目后期再转为正式文档;写文档发生在编码之后(至少同时)更准确,因为初始设计在构建测试循环中保持不变的可能性与模块数和程序员数成反比;
  • 十年后的结语中,作者更强调架构文档:从源码中反推架构令人望而却步,而工具无法从大量细节中提炼关键信息,所以要由人编写和维护聚焦关键类及其关系的图和文本。
这张卡片看不懂?

已有反馈 · 0 / 10 条

    还没有人提交反馈。

    在整书笔记中的位置

    原书出处 · 1 处

    参考来源

    - 位置:《敏捷开发(纪念版)》第40章《附录B 源码即设计》什么是软件设计?;结语(源文件:extracted/敏捷开发(纪念版)/_epub-src/Min Jie Kai Fa (Ji Nian Ban )_split_052.html,来源项目 book-sources) - 结论依据:附录B说明辅助文档的两个用途——记录问题域中不直接进入设计的信息和难以从源码提取、最适合用图形表达的设计内容,强调源码决定真实设计、辅助文档保持最小并在编码后编写,结语补充架构文档需由人编写维护。 - 原始内容:辅助文档的首要用途是从问题域中捕获重要的信息,这些信息是不能直接在设计中使用的。