《编程匠艺》读书笔记之十七

第十九章 注意细节——编写软件规范

• 编写和处理规范是程序员应该具备的一项非常重要的技能。用自然语言沟通，与用代码沟通一样重要。
• 规范使一些正式文档，它们构成了开发过程的一部分，用于提供内部的软件文档。
• 规范有助于你更加聪明的工作，并编写出更好的软件，不过，糟糕的规范会起到完全相反的作用。
• 对于软件开发过程而言，重要的不仅仅是软件规范是否存在，而且还有软件规范的质量。
• 规范是团队内部和团队之间进行沟通的一种形式。它的重要性会随着项目规模的增大而急剧增加。
• 编写规范有助于是我们的信息：1. 更加安全；2. 可访问；3. 更加准确。
• 如果你发现你的文档不具有可塑性也不可维护，那么你的软件开发就要遭殃了。优秀的程序员会考虑让他们的规范就像他们的代码一样可塑。
• 需求规范：它极为详细的列出了代码预期应该具有怎样的行为，它必须涉及所有重要的、高风险的、高价值的各种系统行为，非常全面而且没有歧义。
  
  需求规范需要包括：
• 功能需求。描述程序必须实现哪些功能。
• 性能需求。说明了软件的速度应当多快，以及是否有某些操作必须限时完成。
• 互操作需求。描述了软件必须与之交互的其他软件、硬件和外部系统。
• 未来的操作需求。确定当前必须容纳的功能，即使这些功能还不能马上实现。
  
  
• 客户必须同意并签署需求规范，它构成了软件开发人员和客户之间的一个有效的合同。
• 软件需求必须尽早得到，以便设定预期、预防功能蠕变并减少开发人员的焦虑。
  
  我们使用需求规范的目的：
• 保证项目按轨道前进，并按时完成。
• 提高客户满意度。
• 减少bug。
• 保持你的头脑清醒。
  
  
• 功能规范：描述了软件爱你的可以观察到的行为。它完整并清晰的描述了它的公共接口，以及所有外部数据的结构和格式、与其他组件或者规范之间的依赖关系。
• 如果你的软件任务没有得到充分的规定，那么在你编写好功能规范，并且大家都同意它是正确之前，先不要开发编写代码。
  
• 系统体系结构规范：描述了软件解决方案的整体情况和结构。
• 体系结构会影响开噶的后期阶段，这里的一个错误或歧义会传递下去，而在后面的阶段会变成严重的缺陷。
• 用户界面规范：包含了关于用户界面的信息。它也许会描述一个GUI应用程序，或者一个基于网络的界面、一个有声的电话菜单系统、一个为盲人设计的界面或者一个简单的单LED显示。
• 设计规范：描述了组件的内部设计，描述了功能规范将会怎样或已经怎样实现。它描述了所有的内部API、数据结构和格式。
  
• 对于大多数软件来说，设计规范是随着代码一同编写的，或者是在编写了代码之后才编写的。
• 使用文学性编程工具来编写你的技术文档，不要编写很容易过时的字处理文档。
• 测试规范：描述了对软件的特定部分进行测试的策略。它包含了一张所有必须执行的测试列表。
• 如果你能为你的软件创建程序性的单元测试，那么就执行这个测试，而不要创建冗长的测试规范。
  
  虽然每种规范都包含不同的内容，但是所有的规范都必须：
• 正确。如果一个规范可以用不止一种方式来解释，那么这个规范就称不上“规范”。
• 可理解。最好的规范应该从读者的角度编写，而不是从作者的角度编写，信息的构成形式有利于让新来的人能够理解，而不是为了方便作者。
• 完整。规范中的细节水平应该明显低于实现中的细节水平，否则规范要么就是描述过于细致，要么就是内容过于庞杂，影响理解。
• 可验证。规范的内容必须是可验证的，这在很大程度上相当于内容要正确、无歧义并且完整。
• 可修改。注意没有什么东西是不可改变的。
• 自描述。
• 可跟踪，应该有一个文档控制过程，以及一个用来存放所有文档的中央文件存储库。
  
  编写规范的过程非常简单，如下：
• 选择合适的文档模板，如果没有，建立一个。
• 编写文档。
• 评审。
• 文档入库。
• 在今后的开发过程中，对文档进行维护。
  
  
• 正式的文档应该以第三人称和现在时态进行编写。
• 程序员们喜欢的是编程，而不是编写长篇的文档。大多数程序员都没有良好的写作技巧，他们编写的代码很优雅，但是写出的文章却很糟糕。
• 编写规范的行为本身就会要求你开动脑筋。
• 通过避免编写规范来节省时间，几乎肯定是一种虚假的节约行为，规范有助于人们在沟通时节约很多时间。
• 避免规范的编写非常危险，而且也很不专业。如果没有足够的时间来编写文档，那么也很可能没有足够的时间来编写代码。
  
  
• 优秀的程序员：1. 了解规范的重要性，并使用规范来使他们的开发生活更轻松；2. 了解所需的适当的文档化水平；3. 希望提高他们的编码技巧，并且寻找审查和实践的机会。
• 糟糕的程序员：1. 一头扎进编码任务中，完全不考虑设计、文档和评审；2. 在编写时不用心思考，写出的规范没有结构，难以理解；3. 逃避规范的编写，觉得这很枯燥，而且毫无意义。
  
•