什么是好的规范?[闭门]

最好的规范是:

1. 存在
3. 可以用尽可能少的方式来解释
6. 简洁
7. 是一致的
8. 随着需求的变化定期更新
10. 是可测试的

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

观众

• 正在签名的业务所有者 关闭系统。

• 系统(可能是您,也可能不是您)

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

• 了解系统

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

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

• 这个 企业主

• 开发者

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

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

• 维修人员 需要与开发人员基本相同的信息以及描述体系结构的系统路线图文档。

• 积分器

规范的关键组件:

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

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

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

• 数据验证和业务规则:

• 接口的定义: 如果您有其他系统可以使用的公开接口,则需要非常严格地指定这些接口。较简单的internet RFC给出了相当好的协议设计示例,并要求接口文档示例有一个良好的开端。清楚地定义接口并不容易,但几乎可以肯定的是,这样做会让您省去很多麻烦。

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

Joel (关于《软件论》的名声)写道 good series of articles 无痛功能规范 我在很多场合都提到过。这是一套相当好的文章,值得一读。在我看来,你的目标是以尽量减少歧义的方式清楚地解释系统应该做什么。将规范视为参考文档是非常有用的——不同的利益相关者可能希望能够轻松查找哪些内容。

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

做规范的回报是没有其他人愿意做它们。当您编写了可能是系统中唯一重要的文档时,您就可以发号施令了。任何其他有议程的人都必须游说你改变规范,或者以某种方式在项目上强加一个相互竞争的规范。这是笔比剑强大的一个很好的例子。

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

根据我的经验,如果规范具有以下内容,那么它将有更多的机会被阅读:

• 尽可能使用图表-图片价值1000字
• 有一个标题页,清楚地指出规范所描述的内容
• 具有在整个文档中使用的样式。使所有标题具有相同的字体、大小和样式。使字体始终相同,使用相同的项目符号样式等

作为为客户开发定制软件的人, .

无论您的规范有多完善,如果客户没有明确书面同意,他们会更改规范,并期望您无缝地执行更改,破坏您美丽的体系结构。。。

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

Painless Functional Specifications Joel测试文章的后续内容。它们也出现在“Joel on Software”一书中。

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

• 简短的描述,“一页纸”
• 一个上下文关系图——上下文在哪里 系统
• 用例/用户故事
• GUI原型或纸质原型, 如适用
• (表演等)

如果你一开始就说明用户的目标或者某个函数的全局概念,那么它也会有所帮助;而不是填写确切的执行情况。对我来说,这总感觉像是缩小了思想开放的范围,或是使用了不那么有创意(更有用)的解决方案。所以你应该保持“所有选项都是开放的”。

实例 你正在写一个软件来测量“X”。

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

使用:

为什么? ? 实施某事。现在这看起来可能很琐碎,但我感觉“程序员”倾向于在解决方案中思考,而不是在问题(或情况)中思考。当您添加更多功能时,这一点变得更加明显,因为使用向导或自动化流程可能会更好,但您已经将想法缩小到使用按钮。

对于功能需求,或者更具体地说,行为需求,我喜欢使用黄瓜和小黄瓜。

下面是简单映射应用程序中新功能的简单简短规范示例。该功能允许小企业注册地图平台,并在类似谷歌地图的服务上添加他们的营业地点。

Feature: Allow new businesses to appear on the map

  Scenario Outline: Businesses should provide required data

    Given a <business> at <location>
     When <business> signs up to the map platform
     Then it <should?> be added to the platform
      And its name <should?> appear on the map at <location>

    Examples: Business name and location should be required
      | business         | location | should?   |
      | UNNAMED BUSINESS | NOWHERE  | shouldn't |

    Examples: Allow only businesses with correct names
      | business         | location                  | should?   |
      | Back to Black    | 8114 2nd Street, Stockton | should    |
      | UNNAMED BUSINESS | 8114 2nd Street, Stockton | shouldn't |

    Examples: Allow businesses with two or more establishments
      | business      | location                | should? |
      | Deep Lemon    | 6750 Street South, Reno | should  |
      | Deep Lemon    | 289 Laurel Drive, Reno  | should  |

    Examples: Allow only suitable locations
      | business      | location                | should?   |
      | Anchor        | 77 Chapel Road, Chicago | should    |
      | Anchor        | Chicago River, Chicago  | shouldn't |
      | Anchor        | NOWHERE                 | shouldn't |

该规范看似简单,但实际上相当强大。

• Gherkin是一种商业可读语言,用于根据给定的When-Then模板编写规范文档。模板可以自动进入验收测试。自动化规范确保它保持最新,因为捕获的对话直接与测试代码关联。这样,测试就可以用作文档,因为每次代码更改时,小黄瓜特性都必须更改。

• 小黄瓜规范和测试代码之间的直接联系通常通过创建和培养一个活文档系统来减少浪费造成的损害。由于测试的频繁验证,就像在连续集成系统中一样,您可以知道,当这些测试仍然是最新的并且您信任您的测试时,您可以使用相应的小黄瓜规范作为整个系统的文档。

• 事实上,有一种完整的方法称为“示例规范”,它使用了像Gherkin这样的工具。通过在规范文档中使用具体、离散、明确的示例,通过为您提供一个与业务涉众对话的框架,通过示例规范的实践减少了误解和返工的可能性。

“Writing Great Specifications” 探索编写伟大场景的艺术,并将帮助您将可执行规范作为开发过程的核心部分。

如果你有兴趣购买写伟大的规格,你可以 :)

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

KiwiBastard 我会添加write-bullet-like,使每个bullet都可以测试。

它应该是足够的信息,以确保实现“如预期的那样”,而不提供太多不必要的额外噪声。

实际上,大多数人都错了,因为他们专注于简单的事情(这是最不必要的),而回避困难的事情(这是你真正想要锁定的)。我看到过太多的2英寸文档完全没有抓住要点,很少有3页的文档完全抓住了要点。

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

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

保罗。