2005-09-01-感悟软件工程二十七

2005-09-01

感悟软件工程二十七

文档

程序文档是向读者解释程序做什么以及如何实现的书面描述。内部文档是直接在代码中的描述性材料，所有其他的文档都是外部文档。

内部文档包含的信息是用来指导别人阅读程序源代码的，它提供摘要信息定义程序，描述数据结构、算法和控制流。

1.头注释块。包括：组建叫什么；组件的作者；组件在整个系统设计中完成哪个部分的功能；组件是三狠么时候编写和修改的；为什么要有这个组件；组建如何使用数据结构、算法和控制。

2.其他程序注释。即使结构清晰，书写良好的代码中，注释也占有很重要的地位。注释要能反映真实的代码行为，另外，确保通过注释，而不是用过使用显而易见的标示和变量名增加新的信息。

3.有意义的变量名和声明表示。字母语句标示应该告诉读者做标记的程序段时干什么的；数字标示按照习惯是用升序排列的，而且还根据相关的目的组织到一起。

4.增进理解的格式。声明的缩进和间隔能直观的体现基本的控制结构。

5.记录数据。无论是结构化编程还是面向对象编程，内部文档应该包括对数据结构和使用的描述，特别是数据流图和数据字典很直观。

外部文档是为了那些可能不接触实际代码的人，因为内部文档的阅读对象是定位在于编程人员，而像向顾客再让他们来阅读内部文档显得不切实际。外部文档主要有三个方面要注意：描述问题、描述算法和描述数据。从某种意义上说，设计是外部文档的骨，而叙述讨论代码组件的细节则是肉，至于是不是有血有肉就和编写代码没有关系了。