软件工程概论（七）编写程序

I. Programming Standards and Procedures编程标准和过程

Standard format for comments

从解决方案到程序有三方面困难：
用图标描述的内容不一定适合写成代码 。
要让别人以后也能看懂我们的代码。
创建易于复用的代码，还要利用设计的组织结构、数据结构、程序设计语言等特性。

对单个开发人员标准的意义 ：
标准和过程能够帮助自己避免犯错 。
清晰的文档在自己重返工作时不会迷茫，也便于查错。
有助于将设计转换为代码，并维护设计和代码的一致性，出错的可能性也降到了最小。

设计和实现的匹配
程序设计构件和程序代码构件之间建立直接的对应关系低耦合、高内聚、定义明确的接口也是程序的特性。
从代码出发，对算法、函数、接口和数据结构进行跟踪，从代码到设计也应该是这样。
改变从高层设计开始，但要通过底层设计追踪到必须修改的代码，所以二者的一致性是根本基础，如果没有这种链接，那么测试、维护和配置管理就毫无意义。

II. Programming Guidelines指导原则

一般来说，程序构件至少包括三个主要方面。控制结构、算法、数据结构。

控制结构

要使代码反映出设计的控制结构，因为除了OO是基于状态和变量的变化的，一般控制都依赖于代码本身的结构，所以不要让读者在代码之间急剧跳转，要能够易于从上到下阅读一个构件。
根据模块化的块来构建程序，可以在不同的层次隐藏实现细节，使得整个系统易于理解、测试和维护。可以将程序构件本身看作模块化的，并采用宏、过程、子例程、方法和继承隐藏细节。代码构件越是模块化，就越容易维护或复用。可以将修改与特定的宏、子例程或其它子构件构件隔离开。
通用性是一种优点，不要让代码太过特殊，同时，不要让构件过分通用化，从而影响其性能和对它的理解。
代码必须能让读者看清楚在构件之间传递的是哪些参数，便于测试和维护，换句话说，构件之间的依赖关系必须是可见的。由于同样的原因，就像系统构件的设计要彼此隐藏信息一样，程序中的子构件之间也应该彼此隐藏具体的计算细节。

算法

算法逻辑是确定的，但实现语言和硬件会有不同的影响 重点关注的地方是实现的性能或者效率。要使代码运行的尽可能快，困难会伴随着一些隐藏的代价。
编写更快代码的代价。困难会使代码更复杂，从而花费更多的时间编写代码。
测试代码的时间代价。代码的复杂度要求有更多的测试用例或测试数据。
用户理解代码的时间代价。 需要修改代码时，修改代码的时间代价。
执行时间只是代价因素的一个很小的部分，要在设计质量、标准和客户需求之间平衡考虑。特别是，不要牺牲代码的清晰性和正确性去换取速度。如果速度确实重要，要观察编译器是如何优化代码的。

数据结构

编写程序时，要安排数据的格式并存储数据，使得数据的管理和操纵更为直观。有几种使用数据结构的技术提出应该怎样对程序进行组织。
保持程序简单。
用数据结构来决定程序结构。

III. Documentation文档！！

程序文档是向读者解释程序做什么以及如何做的书面描述。

Internal documentation内部文档

内部文档是直接写在代码中的描述性素材。

内部文档包含的信息是面向阅读程序源代码的那些人，因此，它提供概要信息以识别程序，描述数据结构、算法和控制流。通常情况下，这种信息以一组注释的形式放在每个构件的开始部分，称为头注释块。
1、头注释块中必须包含下列信息：
构件名字是什么 。
谁编写了这个软件。维护测试小组可以联系到编写者，以提出问题或取得意见。
构件应该装配在整个系统设计中的哪个地方。因为构件是更大的系统的一部分，头注释块中应该指明如何将它装配到构件层次中。
构件是在何时编写和修改的。便于追踪变化。
为什么要有这个构件 。
构件是如何使用数据结构、算法和控制的。
需要更详细的信息来解释构件是如何完成目标的，头注释块应该列出：
名称、类型、每个主要的数据结构和变量的意图
逻辑流、算法和错误处理的简短描述
预期的输入和可能的输出
帮助测试的工具，以及如何使用它们
预期的扩充或改正。

2、其它程序注释
结构好就清晰易懂，代码本身就是信息源。
逐行解释或区分步骤和活动
伪代码可以提供注释基础
当修改代码时，要更新注释以反映代码的变化。
边写代码边写注释。
难以注释的代码要小心。

3、有意义的玻变量名和语句标记
选择能够反映变量和语句的用途及含义的名字

4、安排格式以增强理解
注释的格式能够帮助读者理解代码的目标以及代码是如何实现目标的。声明的缩进和间隔能够反映基本的控制结构。安排语句的格式，使得注释处于页面的一边而语句处于另一边。

5、文档化数据
内部文档应该包含对数据结构及其使用的相关描述。

External documentation外部文档

所有除了内部文档的文档都是外部文档。

不看代码的人阅读外部文档
由于软件系统是根据相互关联的构件来构造的，外部文档通常包括系统构件的概述，或者若干组构件（如用户界面构件、数据库、管理构件、快速计算构件）的概述。图及其伴随的叙述性描述说明构件中的数据是如何被共享的，以及如何被一个或多个构件使用。一般来说，概述描述了如何从一个构件向另一个构件传递信息。
（从系统层面来看，构件的关系，继承等层次）

外部构件文档是整个系统文档的一部分。在编写软件时构件结构和流程的很多基本原理已经在设计文档中详细的加以描述。从某种意义上讲，设计是外部文档的骨架，而叙述性描述讨论代码构件的细节，是外部文档的血肉。
1、描述问题
构件要解决什么问题，为什么选择这个方案，它不是重复需求，而是说明对需求的应对
2、描述算法
解释构件使用的每一个算法，包括公式、边界或特殊条件，甚至它的出处或对它的参考书或论文的引用，特例的处理情况。
3、描述数据
在构件层次查看数据流，数据流图与数据字典的引用，对象数据的交互等等。