1.2　编写软件说明

你可能熟悉典型的提纲：一种层次的、缩进的条目清单。这是个跟踪项目的奇妙方法。有许多应用软件都保存着这样的清单。但在阅读本章时，请考虑下面所有这些关于软件设计和开发编写的不同实践方法。

·传统提纲很适合于在最初理清头绪时探寻各种念头，组织需求文档，并与团队交流复杂的想法。在项目的任何位置，如果你发现自己受某个复杂问题的困扰，可以考虑做个传统提纲来理解这个问题。有分析头脑的人会觉得提纲是组织信息的最自然方式。Mac和iPad上有一些不错的提纲应用软件，它们能让你更方便。

·无格式文本是个速记你的想法和要考虑的事项的简单易行的办法。但将文本文件层次化、条目化有些困难。它们易于共享，尤其在通过云服务将其保持同步时。

·待办事项应用软件的任务能够在你规划出要做的事情后，让你按部就班地去做。它们往往只是短期使用，且供个人使用，而不会为团队提供对某个话题的全面、准确定义的记录。

·缺陷跟踪数据库中的记录单可以让团队的每个人都更容易看到目前问题的情况，围绕它所进行过的讨论，以及人们提到过的解决方案。但它不适宜给出整体概述。你不能指望缺陷跟踪帮助你了解任何超出某个单独问题的内容。

·纸和白板对于快速进行个人规划，或者在与别人会面时是个极好的工具。没有比这种方式更容易地完美结合提纲与草图了。一旦你和别人在白板做了交谈，就可以拍个照片永久保存，以备日后你回忆“那次会议上我们是如何考虑的”。

·在项目管理软件中的计划是个跟踪待办事项的正规方法。对于项目经理等管理者来说，这是可以在一张大图上观察项目现状的宝贵工具。但在面对困难的设计问题时，它们不能帮助观察决策之间的细节，因此也就没那么有用了。

·设计说明文档即“spec”，是团队对一份软件计划和意图的明确、完整的描述。这取决于你的组织和过程的正规程度，对于这类文档，可能会要求遵循IEEE 1016标准。

最可能的是，你会组合使用这些工具，来保持对设计项目若干层次细节的跟踪：例如，用文本文件报告缺陷，记录白板照片，列出若干提纲清单等。你喜欢用哪些工具取决于你需要什么程度的细节，你是否与团队协同工作，以及你最擅长运用哪些应用软件。

重要的是，把全面的、条目化的事物放在一起，从而通盘考虑项目：从最泛泛的目标到细微的、吹毛求疵的细节。有些提纲有几百个条目，例如，将某复杂应用软件的所有组件都列出来；有些提纲则只有几条很精确的决策，花几个小时就能搞清楚。

即使你没准备正式的文档，有一份（或一套）文档仍然很有价值。你可以让这些文档正规或者随意，但要充分描述团队对其所做项目的理解。（即使你未与一个团队协同工作，这仍然很有用。）要确保这些说明文档像源代码一样，也放入版本控制系统中，确保它们总是最新的。

还要将设计里（以及讨论中）被摒弃的想法保存起来，这些想法说明了你没有采取某些看似诱人的选择的原因。被摒弃的想法可以防止你为同样一件事情而纠结，它们应成为应用软件的“需求禁忌”，这将在后面论述。将软件按说明文档创作是个好方法，通过它不会丢失对待办重要事宜的跟踪，人们也不会误解软件未做完的地方是有意为之的，还是终归要做到的。