什么使得一个好的规格？
Joeltesting中的一个项目是项目/公司应该有一个规范。
我想知道是什么使一个规范好。 有些公司会写一些没有人读过的无用规格，有些则不会写任何东西，因为“没有人会读它”。 那么，你把什么放入你的规格？ 两个极端之间有什么好的平衡？ 有没有什么特别重要的东西，真的（！）应该总是被logging在规范中？
最好的规范是：
- 存在
- 描述什么，而不是如何（没有解决scheme）
- 可以用尽可能less的方式来解释
- 是广泛分布的
- 被所有有关方面同意为规范
- 简洁
- 是一致的
- 随着需求的变化而定期更新
- 尽可能多地描述可能和实际的问题
- 是可testing的
什么放在一个规格
你需要看看规范的受众，找出他们需要知道的东西。 这只是你和业务赞助商之间的文件吗？ 在这种情况下，它可能相当轻量级。 如果这是一个100多人年的J2EE项目的function规范，它可能需要更多的细节。
观众
关键问题是：谁将阅读规范 – 规范将有几个潜在的利益相关者：
-
正在签署系统的企业主。
-
正在构build系统的开发人员（可能或可能不是你）
-
质量保证人员必须为其编写testing计划。
-
维修人员想了解这个系统
-
其他项目的开发人员或分析人员可能希望将其他系统集成到其中。
典型关键利益相关者的要求
-
企业主需要对系统工作stream程和业务规则有清晰的认识，以便他们有机会了解他们已经同意的内容。 如果他们是规范中唯一的主要受众，那么专注于用户界面，屏幕画面工作stream以及业务和数据validation规则。
-
开发人员需要一个数据模型，数据validation规则，部分或全部的用户界面devise和足够的预期系统行为描述，以便他们知道要构build什么。 如果您正在为开发人员撰写专注于用户界面，映射到用户界面中的数据模型和规则。 这应该比你自己进行开发更加详细，因为你是两个第三方沟通的中间人。
如果你指定两个系统之间的接口，这必须非常精确。
-
质量保证人员需要足够的信息来制定如何testing和validation应用程序的逻辑，validation和预期的用户界面行为。 针对开发人员和质量保证人员的规范需要相当明确。
-
维护人员需要与开发人员相同的信息以及描述该体系结构的系统路线图文档。
-
集成商需要一个数据模型，并明确界定任何接口。
规范的关键组件：
我假设一个人正在写商业应用程序的规格，所以下面的内容是面向这个。 其他types的系统的规格将有不同的重点。 根据我的经验，function规格的关键要素是：
-
用户界面：屏幕模型和屏幕之间系统和工作stream程交互行为的描述。
-
数据模型：定义数据项并映射到用户界面。 用户界面映射通常在描述用户界面的规范的位中完成。
-
数据validation和业务规则：需要对数据进行什么检查以及正在进行哪些计算以及定义。 这里的例子可能非常有用。
-
接口定义：如果你有其他系统可以使用的接口，你需要指定那些相当紧密的接口。 简单的互联网RFC提供了很好的协议devise实例，为接口文档的例子提供了一个良好的开端。 明确定义界面并不容易，但几乎可以肯定的是，你可以将悲伤的事情解决掉。
-
胶水：这是用例，工作stream程图和其他需求相关工件的帮助。 一般来说，这些列表是毫无意义的，但是在这种types的文档有助于将项目置于上下文中的系统中将存在关键的区域。 我的经验是，select性地包含用例和其他需求级别的描述在很大程度上增加了规范的清晰度和含义，但为与系统的每一次单独交互编写用户故事都是浪费时间。
乔尔 （“软件”的名声）写了一系列关于这个被称为无痛function规范 的文章 ，我曾多次提到过这些文章。 这是一个相当不错的文章，值得一读。 在我看来，你的目标是清楚地解释系统应该以最小化歧义的方式做什么。 将规范视为参考文档是非常有用的 – 各种利益相关者希望能够轻松查找什么内容。
写了一个关于规格的圆点集，明确的交stream部分比看起来更难。 规格实际上是不平凡的技术文件，是一个技术写作和编辑技能的testing。 你实际上正在写文档描述什么人应该build立。 做好规格是一种艺术。
做规格的回报是没有人愿意去做。 正如你写了什么可能是唯一对系统重要的文件，你可以做主。 任何有议程的人都不得不游说你改变规格，或者以某种方式在项目上强加一个竞争规格。 这是笔比剑更强大的一个很好的例子。
编辑：这是我的经验，关于“如何”和“什么”之间的区别的辩论往往是相当自利。 在任何非平凡的项目中，数据模型和用户界面都会有多个利益相关者，而不是所有的人都是系统的开发者。 在数据仓库中工作时，人们会对随着应用程序数据模型成为免费项目而产生的混乱感到厌恶，而且PFS应该给予一个规范必须迎合的潜在利益相关者的感觉。
事实上，某人拥有数据模型或用户界面devise并不意味着这些只是由法定决定 – 可以有一个话语和谈判过程。 但是，随着项目越来越大，所有权和一致性的价值越来越大。 过去一直以来我认为，认识一位优秀分析师的价值的最好方法就是看到一个糟糕的分析师所造成的损失。
根据我的经验，如果具有以下条件，规范将有更多被阅读的机会：
- 尽可能使用图表 – 图片价值1000字
- 有一个标题页，清楚地表明了规范描述的内容
- 有一个在整个文档中使用的风格。 使所有标题相同的字体，大小和样式。 使字体一直贯穿始终，使用相同的子弹风格等
- 不要唠叨 – 要清楚简明扼要，并且不要添加额外的东西来填充文档。 如果一个点不能用几行文字来解释，那么你可能需要进一步细分
我曾经在公司看过写规范的人不懂系统。 这几乎是通过编写规范来学习系统的一种方式。 这通常以眼泪结束
作为为客户开发定制软件的人， 最好的规范是客户签署的规范 。
不pipe你的规格有多精炼 – 如果客户没有明确表示同意，他们会改变它，并希望你无缝地改变他们的变化，破坏你美丽的build筑…
好的规格应该包含可测量和可validation的要求。 在看每个要求时，你应该能够很容易地回答这个问题：“我如何certificate我已经达到了这个要求？”。
阅读Joel的一系列“ 无痛function规格 ”跟进Joeltesting文章。 他们也出现在“Joel on Software”一书中。
取决于项目的规模，以及（像所有的架构决策一样）约束是什么。 一个好的开始是
- 一个简短的描述，一个“传呼机”
- 上下文图 – 边界在哪里，与系统有什么相互作用？
- 用例/用户故事
- GUI原型或纸张原型（如果适用）
- 描述所需的非function性要求（性能等）
最重要的是要有一个验收testing，即对可以检查的事情的可testing的陈述，以及在这些事情完成时，项目已经完成的协议。
如果你从描述用户的目标开始，或者某个function的全局思想是什么，这也是有帮助的。 而不是填写具体的实施。 对我来说，这总感觉就像缩小开放心态或使用较less创造性（更有用）的解决scheme。 所以你应该保持“所有选项打开”。
示例编写软件来测量“X”。
而不是说明：必须有一个开始button和一个保存button。
使用：用户必须能够开始测量并保存。
为什么 ？ 因为在第一种情况下，你已经确定了解决scheme，而第二种情况则给了你如何实现某些东西的灵活性。 现在这可能看起来微不足道，但我觉得“程序员”倾向于在解决scheme中而不是在问题（或情况）中多思考。 当你添加更多的function时，这变得更加明显，因为使用向导或者自动化过程可能会更好，但是你已经缩小了使用button的想法。
对于function要求 – 或者更具体的行为要求 – 我喜欢使用黄瓜和黄瓜。
下面是一个简单的地图应用程序中的新function简单和简短规范的例子。 该function允许小型企业注册到地图平台，并将其业务地点添加到类似Google地图的服务中。
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的规格。 他们最好简单而简单。 不要编写长的规范文档，而是通过在每次迭代中编写新的规范，让规范套件与您的产品一起发展。
-
小黄瓜是基于Given-When-Then模板编写规范文档的商业可读语言。 模板可以自动进入验收testing。 规范的自动化确保它保持最新状态，因为捕获的对话直接与testing代码相关联。 这样，testing可以用作文档，因为每当代码改变时，Gherkinfunction都必须改变。
-
当每个业务规则都被赋予一个自动化testing时，小黄瓜的规格变成所谓的可执行规范 – 可以作为计算机程序运行的规范。 该程序testing验收标准是否正确实施。 所以在这一天结束的时候，我们对于我们的产品是否真的在做我们期望的事情这个问题得到了一个肯定或不答的答案 – 这本身就是非常有价值的，因为它有助于制作更好质量的软件。
-
小黄瓜规格和testing规范之间的直接联系往往通过创build和培养一个生活文件系统来减less浪费。 正如在持续集成系统中一样，由于频繁的testingvalidation，您可以知道即时获取仍然是最新的，而且当您信任testing时，您可以使用相应的小黄瓜规格作为整个系统的文档。
-
实际上，有一个称为“按规范进行规范”的整个方法，使用了像小黄瓜这样的工具。 通过示例规范的规范减less了误解和返工的可能性，为您提供了与业务利益相关者交stream的框架，方法是强制您在规范文档中使用具体的，分散的，明确的示例。
如果你想阅读更多关于黄瓜，小黄瓜，BDD和规范的例子，我写了一本关于这个问题的书。 “写出优秀的规格”探索写好场景的艺术，并将帮助您将可执行规范作为开发过程的核心部分。
如果您有兴趣购买“Writing Great Specifications”，则可以使用促销代码39nicieja2 🙂 节省39％
我认为编写“用例”应该可以节省大量的页面
+1 @ KiwiBastard ，我会添加书写子弹，并使每个子弹可testing。
描述实施所需的所有重要信息的蓝图，但不会浪费任何努力来描述所有必要的微不足道的或明显的信息。
应该有足够的信息来确保实施“如预期”，而不会提供太多额外的噪音，这是不必要的。
在实践中，大多数人认为这是错误的，因为他们专注于简单的东西（这是最不必要的），并且避开困难的东西（这是你真正想要locking的东西）。 我已经看到了太多的2英寸的文件，完全和完全错过了这个观点，很less有3页文件被打到了死angular。
规格不必太长，他们只需要包含正确的东西！
（提示：如果程序员在编码时没有看这个页面，那么可能不需要）
保罗。
