如何编写功能规格说明书？

Question

我们经常编写功能或类，它们的逻辑非常复杂。如果这些结构没有规范，即使是我们自己也很难掌握其中的思想。

你如何为复杂的函数和类编写规范？

请分享一下你自己的经验，而不仅仅是一些链接，谢谢。

- MemoryLeak

---

我已经编辑了你的英文，我相信我知道你的意思...如果你改回去，我不会生气的。 :-) - Paul Nathan

请查看Joel on Software。还有这里和这里。甚至有一个真实的例子。 - user47559

你是在寻找关于编写实际代码结构规范的技巧，还是针对程序的原始用户功能？在我的公司中，实际代码结构规范文档被称为“设计规范”，而用户功能描述被称为“功能规范”。Joel on Software的答案描述了用户功能规范。 - J. Polfer

我认为我需要一份“规格文件”，谢谢 Paul Nathan。 - MemoryLeak

重复的问题，类似于https://dev59.com/sHNA5IYBdhLWcg3wL6oc - anon

Answer 1

我认为功能规格说明书最大的挑战不在于格式本身，而是要让它与驱动它们的事物（需求）和基于它们构建的内容（测试用例、文档）保持同步。

因此，我更喜欢采用基于模型的方法来处理这个问题，而不是纸质方式。

我使用UML建模工具（Sparx Systems的Enterprise Architect，但其他工具也可以）将项目的所有信息捕捉到一个地方，并在它们之间建立可追溯性。在Enterprise Architect中，我可以通过将需求件和设计件（例如）放在同一图表上并使用鼠标拖动创建连接器来从需求件到设计件建立可追溯性。

我的“功能规格说明书”实际上是一组活动图，每个系统用例一个活动图。每个用例都与必须要有该用例的一个或多个需求相关联。即使是最终用户也很容易跟随活动图并验证它们（将传统的纸质功能规格说明书交给最终用户阅读、理解和验证有多困难？）

类似地，我可以从我的活动图（用例）到特定的设计件（如类图）建立可追溯性。

QA可以对测试用例进行建模，并从其测试用例到用例进行可追溯性。这样，我们就可以看到是否有任何用例没有测试用例（或测试用例不足）。

作为工具的Enterprise Architect的好处在于所有这些设计部件都存储在SQL数据库中，因此我可以运行一些已经积累了一段时间的查询来查找没有任何追溯信息的部件。

- Eric J.

---

“让最终用户阅读、理解和验证传统的纸质功能规格说明书有多容易？” 实际上可能没有太大的差异，但是承认自己无法理解清晰的技术英语的人数要比承认自己无法阅读特定技术符号的图表的人数少得多。 - soru

我们实际上通过预定会议室和投影仪，与适当的业务人员 / 分析师一起走过每个图表来审查规范/图表。不写一行代码之前，我们发现了多少误解和误解，真是惊人。 - Eric J.

Answer 2

您应该对以下主题进行研究（不一定按顺序）：

• 统一建模语言（UML）
• 系统序列图（SSD）
• 用例
• 活动图

这些是软件项目规范最常见的方法。

- rogeriopvl

Answer 3

我看到以上有关链接到Joel的材料而非内联文本的投诉，以下是我对他所说的内容的看法。

在最高层次上，功能规格说明需要向消费者或客户传达程序的目标。我完全赞同Joel：使用严谨的英语（任何语言！）是一种非常强大的工具，所有客户都是专家级别的消化专家，却不是UML专家。

顶层功能规格说明文档（FSD）可以提供一个逻辑框架，以捕获系统要求，形成一个人们可以轻松理解的逻辑模型。

纯需求文档 - 一个FSD之前的东西 - 是一个棘手的问题。很少有人能够在头脑中区分什么是需求和什么是解决方案。因此，最好将需求保持在非常高的水平上，并且作为分析师，专注于FSD。

FSD应该是系统的完整顶层模型，随后的设计过程涉及更详细的模型层次结构。最终的细节是实际代码。

功能规格说明书应该最终成为一组简单的英语陈述。在文档中使用单个标题级别，将段落保持在两个句子的最大长度，并对每个段落进行编号。审查段落并确保每个段落都说了有用的内容。如果没有，请删除它。简短明了！

认真考虑您的FSD中的语言。在段落中具有严格的关键名词定义。这些名词成为您的类。您使用的动词成为您的类方法。就是这么简单！

正如Joel所说，编写句子时要像编译它们一样。例如，写“如果发生某些事情那么做更多”，而不是“如果发生某些事情，做更多”或“当发生某些事情时做更多”。

这些类型的书面模型可以受益于使用特定的图表，例如有限状态图，但要注意不要认为您可以使用一组UML图表来捕获系统。这些东西本身并不足够强大，灵活或严谨，以充当完整描述。从用严格的英语编写的大纲开始，然后根据需要进行补充，这样效果更好。

关于迭代问题，理想情况下，您只需要重新设计模型的较低层次即可。如果您必须更改高层次，则表示出现了严重问题。至于UML工具是否更快地实现重访 - 这是胡说八道！关键在于所有这些描述都要简短而精练。英语是最好的选择，因为我们已经练习了很长时间。

我见过人们花一个下午来尝试使实体图看起来漂亮，以解决重叠线的问题。为什么？你的最终解决方案是二维框和线吗？不是！这就是UML的问题：图表成为分析师自己的目标，阻碍与客户的沟通，而不是帮助沟通。

- Herc