38

Joel 测试中的一项是项目/公司应该有一个规范。

我想知道是什么让规范变得更好。一些公司会编写大量没有人阅读的无用规范,而另一些公司则不会写下任何内容,因为“无论如何也没有人会阅读任何内容”。那么,您在规范中添加了什么?这两个极端之间的良好平衡是什么?有什么特别重要的东西,真的,真的(!)应该总是记录在规范中吗?

4

12 回答 12

54

最好的规格是:

  1. 存在
  2. 描述什么,而不是如何(没有解决方案)
  3. 可以用尽可能少的方式解释
  4. 分布广泛
  5. 被所有相关方同意为规范
  6. 简洁
  7. 是一致的
  8. 随着需求的变化定期更新
  9. 尽可能多且实用地描述问题
  10. 可测试
于 2008-12-18T22:47:09.567 回答
14

在规范中添加什么

您需要查看规范的受众并找出他们需要知道的内容。它只是您和商业赞助商之间的文件吗?在这种情况下,它可能相当轻量级。如果它是一个 100 多人年 J2EE 项目的功能规范,它可能需要更多细节。

观众

关键问题是:谁将阅读规范 - 规范将有几组潜在的利益相关者:

  • 签署系统的企业主。

  • 构建系统的开发人员(可能是也可能不是你)

  • 必须为其编写测试计划的 QA 人员。

  • 想要了解系统的维护人员

  • 可能希望将其他系统集成到其中的其他项目的开发人员或分析师。

典型关键利益相关者的要求:

  • 企业主需要清楚地了解系统工作流程和业务规则是什么,这样他们才能有机会了解他们同意的内容。如果他们是规范的唯一主要受众,请专注于用户界面、屏幕屏幕工作流程以及业务和数据验证规则。

  • 开发人员需要数据模型、数据验证规则、部分或全部用户界面设计以及对预期系统行为的足够描述,以便他们知道要构建什么。如果您正在为开发人员写作,则专注于用户界面,映射到用户界面中的数据模型和规则。这应该比您自己进行开发更详细,因为您在两个第三方之间的通信中充当中介。

    如果您要指定两个系统之间的接口,则必须非常精确。

  • QA 人员需要足够的信息来确定如何测试和验证应用程序的逻辑、验证和预期的用户界面行为。面向开发人员和 QA 人员的规范需要相当明确。

  • 维护人员需要与开发人员大致相同的信息以及描述架构的系统路线图文档。

  • 集成商需要数据模型和任何接口的清晰定义。

规范的关键组成部分:

我假设一个人正在为商业应用程序编写规范,所以下面的内容就是针对这个的。其他类型系统的规格将有不同的重点。根据我的经验,功能规范的关键要素是:

  • 用户界面:屏幕模型以及对系统交互行为和屏幕之间工作流程的描述。

  • 数据模型:定义数据项并映射到用户界面。用户界面映射通常在描述用户界面的规范中完成。

  • 数据验证和业务规则:需要对数据进行哪些正确性检查、进行哪些计算以及定义。示例在这里非常有用。

  • 接口的定义:如果您有其他系统可以使用的接口,您需要非常严格地指定这些接口。更简单的互联网 RFC 提供了很好的协议设计示例,并且是接口文档示例的良好开端。明确定义接口并不容易,但几乎可以肯定会让您免于烦恼。

  • 胶水:这是用例、工作流程图和其他与需求相关的工件提供帮助的地方。通常,详尽列出这些内容是没有意义的,但系统内将有一些关键领域,此类文档有助于将项目置于上下文中。我的经验是,选择性地包含用例和其他需求级别的描述可以大大增加规范的清晰度和意义,但是为与系统的每一次交互编写用户故事是浪费时间。

Joel(以“软件”着称)为此写了一系列很好的文章,称为无痛功能规范,我曾多次推荐人们参考这些文章。这是一组相当不错的文章,非常值得一读。在我看来,你的目标是清楚地解释系统应该做什么,以最大限度地减少歧义。将规范视为参考文档非常有用 - 各种利益相关者可能希望能够轻松查找。

在编写了一组关于规格的圆滑的要点之后,清晰的沟通部分比看起来更难。规格实际上是不平凡的技术文档,是对一个人的技术写作和编辑技能的考验。您实际上是在编写描述某人应该构建什么的文档。做好规格是一门艺术。

做规范的回报是没有其他人愿意做。当您编写了可能对系统具有任何重要性的唯一文档时,您就可以做主了。其他任何有议程的人都必须游说您更改规范或以某种方式将竞争规范强加给项目。这是笔比剑更强大的一个很好的例子。

编辑:根据我的经验,关于“如何”和“什么”之间区别的辩论往往是自私的。在任何不平凡的项目中,数据模型和用户界面都会有多个利益相关者,并非所有人都是系统的开发人员。从事数据仓库工作会让人们体验到当应用程序数据模型被允许免费提供给所有人时所带来的混乱,而PFS应该让人们感受到规范必须迎合的潜在利益相关者集合。

某人拥有数据模型或用户界面设计这一事实并不意味着这些只是由法定决定 - 可以有一个话语和谈判过程。然而,随着项目变得更大,所有权和一致性的价值会变得更大。我过去的观察是,欣赏优秀分析师价值的最佳方式是看到坏分析师造成的损害。

于 2008-12-18T22:19:43.977 回答
11

以我的经验,如果规范具有以下内容,则更有可能被阅读:

  • 尽可能使用图表 - 图片值 1000 字
  • 有一个标题页,清楚地表明规范所描述的内容
  • 具有在整个文档中使用的样式。使所有标题的字体、大小和样式相同。使字体始终相同,使用相同的项目符号样式等
  • DONT WAFFLE - 简洁明了,不要添加多余的东西来填充您的文档。如果一个点不能用几行文字解释,那么也许你需要进一步分解它

我曾在公司中看到编写规范的人不了解系统。这几乎是通过编写规范来学习系统的一种方式。这通常以眼泪结束......

于 2008-12-18T21:42:16.860 回答
4

作为为客户开发定制软件的人,最好的规格是客户签署的规格

不管你的规范有多精致——如果客户没有以书面形式明确同意,他们会改变它,并期望你无缝地进行他们的改变,破坏你美丽的架构......

于 2008-12-18T22:13:31.290 回答
2

好的规范应该包含可测量和可验证的要求。在查看每个要求时,您应该能够轻松地回答“我如何证明我已满足此要求?”的问题。

于 2008-12-18T23:34:47.710 回答
1

阅读 Joel对 Joel 测试文章的后续系列“无痛功能规范”。它们也出现在“Joel on Software”一书中。

于 2008-12-18T21:44:24.640 回答
1

取决于项目有多大以及(像所有架构决策一样)约束是什么。一个好的开始是

  • 一个简短的描述,一个“单传呼机”
  • 上下文图——边界在哪里,什么与系统交互?
  • 用例/用户故事
  • GUI 原型或纸质原型(如果适用)
  • 对所需的非功能性要求(性能等)的描述

最重要的是要有一个验收测试,即可以检查的事情的可测试陈述,以及当这些事情完成时,项目完成的协议。

于 2008-12-18T22:06:44.767 回答
1

如果您首先说明用户的目标或某个功能的全局理念是什么,这也会有所帮助;而不是填写确切的实现。这对我来说总是感觉像是缩小了开放的心态或使用了不太有创意(更有用)的解决方案。所以你应该保持“所有选项都打开”。

示例 您正在编写一个测量“X”的软件。

而不是说:必须有一个开始按钮和一个保存按钮。

用途:用户必须能够开始测量并保存它。

为什么?因为在第一种情况下,您已经确定了解决方案必须是什么,而第二种情况为您提供了如何实现某些东西的灵活性。现在这似乎微不足道,但我感觉“程序员”倾向于更多地考虑解决方案而不是问题(或情况)。当您添加更多功能时,这变得更加明显,因为使用向导或自动化该过程可能会更好,但您已经将想法缩小到使用按钮。

于 2009-03-13T13:33:23.347 回答
1
于 2017-02-01T21:13:23.410 回答
0

我认为编写“用例”应该可以为您节省大量页面

于 2008-12-18T21:36:55.263 回答
0

+1 @ KiwiBastard和我会添加类似子弹的写法并使每个子弹都可测试。

于 2008-12-18T21:49:26.440 回答
0

描述实施所需的所有关键信息的蓝图,但不会浪费任何精力来描述所有必要的琐碎或明显的信息。

它应该只是足够的信息来确保实现“如预期”,而不会提供太多不必要的额外噪音。

在实践中,大多数人都犯了这个错误,因为他们专注于简单的东西(这是最不需要的)而回避困难的东西(这是你真正想要锁定的东西)。我见过太多 2 英寸的文件完全没有抓住重点,而 3 页的文件却很少。

规格不必很长,它们只需要包含正确的东西!

(提示:如果程序员在编码时没有查看该页面,则可能不需要)

保罗。

于 2008-12-18T23:26:22.280 回答