为什么编写软件设计文档很重要

恭喜，你是一个称职的独立开发者。 从你卑微的开始，也许是一名测试员，你已经发展成为一名团队开发人员，然后是一名高级开发人员，现在你已经取得了另一个飞跃，也是最大的飞跃，直接与客户合作。

但是在其他过渡是线性的情况下，最后一个是指数级的。 过去，您从与客户一起工作或本身从事软件业务的雇主那里得到了您的进军命令，但现在所有这些曾经在专家测试、程序管理等之间分配的职责都归您所有。 现在您正在与不从事软件业务的客户合作； 他们在另一个需要软件的企业中，他们对他们想要从你那里得到什么没有一个清晰而准确的愿景。 这是一个远比看起来更大的挑战。

*注意：* 在这里，我描述的是希望从他们的开发人员那里获得一支单人军队的小型客户。 这不是自由职业者可以走的唯一路线，也不是我们在 Toptal 合作的唯一客户，但这是我最喜欢的路线。 当然，如果您是在团队中工作而不是独自工作，则以下某些内容将不适用。 例如，如果您使用敏捷方法或 Scrum，您可能希望构建您的里程碑稍有不同。

你们都听说过沟通的至高无上的重要性。 你无法通过 Skype 获得几句话的简洁描述，然后说“三个月后我完成后见”。 您必须与您的客户保持沟通，并且在工作的每个阶段都确保您对目标有一致的想法，因为确实很少有客户会向您发送线框图和详细的功能规范。 您将对软件的功能、外观和流程有一个非常大致的了解。 如果您根据通常开始时的粗略描述编写应用程序，那么您的客户几乎不可能对结果感到满意。 在每个阶段，您都必须以更接近一致的方式进行迭代。

在自己从事软件业务的公司工作多年，团队中的每个人都来自相同的文化，说相同的母语，在同一个走廊工作，每天见面等等，值得注意的是公司仍然有一半的时间没有得到它想要的东西。 别搞错了：这里的挑战是巨大的。

为什么软件设计文档很重要

因此，当您开始一个新项目时，甚至在您打开 Xcode 或 Visual Studio 之前，您就需要有明确且一致同意的设计目标。 并且这些目标应该在规范文件中建立。 如果客户还没有写，你应该写它，并在你打开你的IDE之前提交给他们审查。 如果你遇到一个客户说，“我们没有时间设计文档”，坦率地说，你应该放弃这个项目，因为你前面有麻烦。 规范不需要特别长； 它可以只有几页，但至少应该布局用户界面，包括线框（如果有 UI 组件），并设置完成里程碑。

没有这份文件，你最终会陷入一个模棱两可的循环中，客户会争论他们告诉你的或你告诉他们的，愤怒地发送以前通信的剪切和粘贴，解释和争论，直到客户要求的时候到来您进行更改以使应用程序符合“他们实际要求的内容”，并希望您免费进行这些更改。

有了这个软件设计文档，任何这样的小问题你都会有答案：当出现分歧时，你可以参考客户同意并签署的规范，指出你已经完全履行了它。 您将对文档进行修改和澄清，而不是愤怒的争论。 如果有的话，客户将首先为让不精确性溜走而道歉。

我们都想要满意的客户。 我们都希望建立友好的工作关系。 我们都希望以出色的工作为荣。 但是，如果对工作的实际内容有任何模糊性，这些都无法实现。 如果您的客户说设计文档有太多额外的工作，那么您的工作就是向他们解释，当由于某种误解需要进行修订时，真正的额外工作将会出现。 如果客户仍然坚持让您在没有此类文件的情况下提前，您应该接受您的关系不可行的事实并走开。

软件设计规范实际上应该指定什么？

至少，它应该是对所需应用程序、完成标准和里程碑的描述。 请记住，您共享的是最好描述为需求和功能文档的内容，而不是实现规范。 除非特定的实现是明确的客户目标，否则如何使其工作取决于您。

用户界面

大多数项目是应用程序，而不是库或框架。 但是，如果您碰巧将其中一个作为可交付成果，那么算您自己幸运，因为用户界面无疑是您的设计文档模板中最有问题的组件，并且几乎总是会导致误解。 许多客户会向您发送由非程序员的图形设计师在图形编辑器中创建的完美插图。 但问题是：这些插图没有说明动画、控制状态（例如，这个按钮是否被禁用？它在不可用时会消失吗？），甚至是按下按钮时要执行的操作。

在开始编写这些插图背后的代码之前，您应该能够回答所有这些问题。 具体来说，您应该知道：

1. 控件是否始终可见和/或启用？ 他们的状态在什么条件下会发生变化？
2. 看起来像位图——是按钮吗？
3. 这些状态和视图之间发生了哪些转换？ 他们应该如何动画化？

如果由您来为客户端的并发生成 UI，请反过来执行相同的操作：使用线框工具并创建一套完整的屏幕布局，包括视图在不同应用程序状态下显示的任何变体。 这可能是一项详尽而乏味的工作，但您不会后悔——它可以使您免于因一个具有重大影响的小误解而重新编写大量代码和重新创建接口。 如果您正在创建一个双重应用程序（例如，同时适用于 iPhone 和 iPad），请为两者创建单独的线框。

屏幕尺寸也很重要。 （在撰写本文时）有三种尺寸的 iPhone 屏幕。 3.5 英寸和 4 英寸屏幕的单独线框可能过多，但您可能必须制作它们； 在大多数情况下，您可以简单地更改比例。

如果您的客户为您提供图形，请确保它们的尺寸正确且纵横比正确； 变形任何具有文本或对象（如圆圈）的位图都会引入扭曲。 如果它们不匹配，请告诉客户以匹配的尺寸重新创建它们。 不要以为您可以将 3.5 英寸的初始屏幕拉伸成 4 英寸的初始屏幕并随其滚动。

功能性

在应用程序设计文档中要问的关键问题：

• 应用程序做什么，它做的速度有多快？
• 什么是可能的故障情况以及如何处理它们？
• 第一次执行时（即安装后）做了哪些一次性操作？
• 如果用户创建任何类型的条目（例如书签），有什么限制？

概括这些想法，并尽可能详细和彻底——因为这里的错误或误解将意味着重写代码。

里程碑

您的规范模板应该布局清晰的里程碑。 如果您的客户编写功能和用户界面设计，您应该随后就一组里程碑达成一致。 有时这些也是计费阈值，但至少它们提供了一个明确的完成指标。 里程碑可能是在功能和/或组件方面； 如果演出涉及一套可交付成果，它们甚至可能是单独的应用程序。 如果可能，里程碑的持续时间应该大致相等。

软件设计规范示例

在这里，我将布置一个适当的设计文档的示例结构。 当然，这个模板应该根据需要进行调整。 对于另一个示例，请参阅 Joel Spolsky 基于此文章的示例规范。 他处理文件的方式略有不同，但有着相似的情绪。

目标声明

包括一个描述项目及其目标受众的简短段落。

功能说明

应用程序做什么？ 用户会遇到哪些应用状态（核心用户场景的高级描述）？

例如，您的功能描述可能如下所示：

• 第一次运行
• 创建一个新的_____（游戏、搜索等）
• 运营
• 背景和前景行为

用户界面

包括每个页面的线框，详细说明：

• 每个控件，包括状态（启用/禁用/突出显示）和操作。
• 支持它们之间的方向和过渡。
• 代表的功能。
• 错误处理。
• 尺寸和约束。

以下是与我最新的 iOS 应用 NotifEye 相关的线框图：

如果你有兴趣，我使用 Balsamiq 的线框图工具制作了这些模型。

例如，您的 UI 描述可能如下所示：

• 导航栏
  • 左侧导航控件：返回首页
  • 标题栏：当前画面或操作名称
  • 新建按钮：创建一个新事物
• 表视图
  • 第 0 节：节标题
  • 第 0 行：
    • 行控制 0（例如，图像）
    • 文本行 0
    • 文本行 2

里程碑

如上所述，完成期限和预期可交付成果。

例如，设计文档模板中的里程碑部分可能如下所示：

1. 外观应用程序显示屏幕并带有临时过渡和示例图像/文本
2. 通信协议：应用程序连接到网络/服务器
3. 功能里程碑 1：……
4. Alpha 应用程序（具有完整功能）
5. 稳定
6. 发布

确保软件文档保持相关性

我并不是说一旦您和您的客户就规范文件达成一致，设计阶段就结束了。 总会有你们没有考虑过的细节，你和客户都会在看中间结果的同时，遇到新的想法、设计的变化、意想不到的设计缺陷和不可行的建议。

设计将不断发展，并且应在文档中捕获更改。 在我 25 年的经验中，我从来没有参与过一个没有发生过这种情况的项目——其中包括我自己的应用程序（即，我是我自己的客户）。 即便如此，我还是创建了一个包含详细规格的设计文档，并根据需要进行了调整。

最重要的是，保持联系。 每周至少几次，联系你的客户，报告你的进展，要求澄清，并确保你们有相同的愿景。 作为您沟通的试金石，请尝试确保您和您的客户对以下三个问题给出相同的答案：

1. 开发人员刚刚在做什么？
2. 开发商目前在做什么？
3. 开发者接下来会做什么？