设计文档的可读性（2）：设计文档的核心原则：写作三要素和四个要点
乔梁约 3 分钟本系列文章将分为三篇介绍设计文档的可读性：
1、为什么要写设计文档并强调其可读性（点击跳转阅读）
2、设计文档的核心原则：写作三要素和四个要点
3、设计文档的最佳实践
如果你写不清楚，你可能没有想象中那么聪明。
-Kurt Vonnegut Jr
1
设计文档的写作也是技术写作（Technical Writing），因此同样强调以下三要素：
清晰
简洁
优雅
技术写作的风格不在本文详细展开，会在后续文章介绍（如果有后续的话），也可参见文末的参考文献。
2
以下是几个系统设计及编写设计文档时需要注意的要点。显然，要点是非详尽的，（更多）设计要点的详细解释会在后续文章介绍（如果有后续的话）。
3.1 任何架构问题都是取舍。
Everything in software architecture is a tradeoff.
在软件设计中，没有任何一个维度有绝对意义上的优劣。 每一个设计决定都需要考量很多产生相互矛盾的因素。
例如，可扩展性和效率相背； 长期效率和短期收益相背；规模化提升了效率，但降低了灵活性。“高内聚低耦合” 便于迭代，但是会增加短期的开发成本。NoSQL 比 SQL 性能高，但代价是功能的大幅降低。
如果一个设计决策看上去没有任何的取舍，往往是因为取舍还没有被识别。
3.2 “为什么” 比 “怎么做” 更重要。
3.3 考虑时间维度
Software Engineering = Coding * Time.
做设计取舍时不能忽略时间维度，只设计某个阶段的终态。设计需要考虑以下方面：
可维护性与可扩展性
考虑实现路径
考虑未来计划
（图片来源于网络）
3.4 避免过度设计（Avoid over design）
设计伊始，界定问题的范围。 一个良好界定的问题是一个良好设计的必要条件。
不要迷信设计模型、设计模式、XX 驱动设计。这些是工具，而非法则。
不要为了解决问题而制造问题。
不要通过复杂的设计来体现工作的难度和深度: 一个困难的问题可能会有一个简单的答案。
不要过于担忧设计被迅速淘汰。
保留可扩展性，但不要在未知时浪费精力扩展。
过度设计的典型例子：
https://github.com/EnterpriseQualityCoding/FizzBuzzEnterpriseEdition
3
最重要的是要知道如何设计，知道自己在设计什么。邓宁·克鲁格效应告诉我们，这未必显然。
乔梁老师开课啦~视频课程《持续部署训练营（Python版）》， 限时特价！
你的软件开发效率够高吗？质量够好吗？你的团队多长时间才能向用户实时推送一个生产变更？你的软件在发布时，你是否因担心软件交付质量而感到压力倍增？你是否遇到过部署失败，甚至导致停机的情况？持续部署可以帮助你消除软件交付的痛苦，让你能专注于为客户高价值的需求，而不会因为这些交付执行类问题而花太多精力。本课程通过学练结合，理论结合实战，让你体验如何使用构建-测试-部署管道，进行持续部署。并练习如何在有效监控部署的同时，逐步发布功能特性，并作数据库结构变化。
（扫码订阅）