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

本文概述

• 为什么软件设计文档很重要
• 软件设计规范应实际指定什么？
• 用户界面
• 功能性
• 大事记
• 软件设计规范示例
• 确保软件文档仍然相关

恭喜, 你是一位能干的独立开发人员。从一开始的卑微(也许是测试人员)起, 你已经成长为团队开发人员, 然后是高级开发人员, 现在你又迈出了一大步, 这是最大的一步, 可以直接与客户合作。

但是在其他转换是线性的情况下, 最后一个转换是指数的。过去, 你是从与客户合作或自己从事软件业务的雇主那里获得订单的, 现在, 所有这些曾经在专家测试, 程序管理等之间分配的职责都由你承担。现在, 你正在与不从事软件业务的客户合作；他们在另一个需要软件的企业中工作, 并且对他们想要的东西没有清晰, 准确的了解。这是一个比看起来更大的挑战。

*注意：*在这里, 我描述的是一些较小的客户, 他们希望从他们的开发商那里获得一支单兵。这不是自由职业者可以采取的唯一途径, 也不是我们在srcmini与之合作的唯一客户, 但这是我最喜欢的途径。当然, 如果你不是一个人在团队中工作, 则以下某些内容将不适用。例如, 如果你使用的是敏捷方法或Scrum, 则可能会希望里程碑的结构稍有不同。

从最初的谦虚的工作(也许是测试人员的工作)开始, 你已经发展为团队开发人员, 然后是高级开发人员, 现在你又迈出了一大步, 其中最大的一次就是直接与客户合作。

大家都听说过沟通的最高重要性。你无法通过在Skype上获得简短描述的几句话, 然后说”我待三个月后见。”你必须与客户保持联系, 并且在工作的每个阶段都要确保你对目标有一致的想法, 因为很少有客户会向你发送线框和详细的功能规格。你将对软件的功能, 外观和流程有一个非常全面的了解。如果你通常根据粗略的描述来编写应用程序, 则几乎没有机会让你的客户对结果感到满意。在每个阶段, 你都必须迭代以达成协议。

你无法通过在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. Facade应用程序显示屏幕并带有临时过渡和示例图像/文本
2. 通信协议：应用程序连接到网络/服务器
3. 功能里程碑1：…
4. Alpha应用程序(具有完整功能)
5. 稳定性
6. 发布

确保软件文档仍然相关

我的意思不是意味着一旦你和你的客户就规范文档达成一致, 设计阶段便告结束。总是会有你未曾考虑过的细节, 你和客户都将在查看中间结果时遇到新的想法, 设计变更, 意外的设计缺陷和不可行的建议。

设计将不断发展, 所做的更改应记录在你的文档中。在我25年的经验中, 我从未从事过一个没有发生过的项目, 该项目包括我自己的应用程序(即我自己的客户)。即使如此, 我仍然创建了具有详细规格的设计文档, 并根据需要对其进行了调整。

首先, 保持联系。每周至少几次, 与你的客户联系, 报告你的进度, 要求澄清, 并确保你拥有相同的愿景。作为沟通的试金石, 请尝试确保你和你的客户对以下三个问题给出相同的答案：

1. 开发人员正在做什么？
2. 开发人员当前正在从事什么工作？
3. 开发人员接下来会做什么？