人月神话-另外一面
2010-03-10 21:55
169 查看
最后一章仍然在讲文档和文档有效性的问题。在开始就指出,我曾经非常勤奋地给我的软件工程师们举办了多年关于文档必要性以及优秀文档所应具备特点方面的讲座,向他们讲述——甚至是热诚地向他们劝诫以上的观点。不过,这些都行不通。我想他们知道如何正确地编写文档,却缺乏工作的热情。所以这章重点仍然放在了如何写文档,文档应该包含哪些核心要素上面。
不同用户需要不同级别的文档。某些用户仅仅偶尔使用程序,有些用户必须依赖程序,还有一些用户必须根据环境和目的的变动对程序进行修改。在需要什么样的文档一段从使用程序,验证程序和修改程序三个方面来谈如何写文档,文档内容应该包含哪些核心要素。使用程序方面的文档发生在程序编写前,要描述清楚程序的目的,范围,场景,输入,输出等各项重要内容。每一个发布的程序需要附加验证说明,即准备我们常做的测试用例,这个发生在验证测试阶段。最后,调整程序或者修复程序需要更多的信息。显然,这要求了解全部的细节,并且这些细节已经记录在注释良好的列表中。
流程图是被吹捧得最过分的一种程序文档。事实上,很多程序甚至不需要流程图,很少有程序需要一页纸以上的流程图。现实中,流程图被鼓吹的程度远大于它们的实际作用。我从来没有看到过一个有经验的编程人员,在开始编写程序之前,会例行公事地绘制详尽的流程图。在一些要求流程图的组织中,流程图总是事后才补上。(在这里我们需要重点强调的就是流程图和各种形式化的表达方式更多应该是应用在构思和前期需求阶段,真正到了设计开发阶段的时候往往并不需要复杂完整的流程图。)
最后谈到了自文档化程序,什么意思呢?核心思想仍然是程序本身应该是可以自解释的,详细的可以看《源代码即设计》一文。在这里有两个重要的阶段,很多时候详细设计可以省略掉,我们的重要设计思路会体现到我们的程序注释中,再进一步很多垃圾无用的代码注释也要去掉,因为代码写好了,代码本身应该具备自解释能力。在源代码编写规范中谈到的注释,空行,缩进,变量命名,循环都有标准的编写规范,如果我们还能多考虑代码的复用和拆分,整个代码文件就能够有很强的可读性。
不同用户需要不同级别的文档。某些用户仅仅偶尔使用程序,有些用户必须依赖程序,还有一些用户必须根据环境和目的的变动对程序进行修改。在需要什么样的文档一段从使用程序,验证程序和修改程序三个方面来谈如何写文档,文档内容应该包含哪些核心要素。使用程序方面的文档发生在程序编写前,要描述清楚程序的目的,范围,场景,输入,输出等各项重要内容。每一个发布的程序需要附加验证说明,即准备我们常做的测试用例,这个发生在验证测试阶段。最后,调整程序或者修复程序需要更多的信息。显然,这要求了解全部的细节,并且这些细节已经记录在注释良好的列表中。
流程图是被吹捧得最过分的一种程序文档。事实上,很多程序甚至不需要流程图,很少有程序需要一页纸以上的流程图。现实中,流程图被鼓吹的程度远大于它们的实际作用。我从来没有看到过一个有经验的编程人员,在开始编写程序之前,会例行公事地绘制详尽的流程图。在一些要求流程图的组织中,流程图总是事后才补上。(在这里我们需要重点强调的就是流程图和各种形式化的表达方式更多应该是应用在构思和前期需求阶段,真正到了设计开发阶段的时候往往并不需要复杂完整的流程图。)
最后谈到了自文档化程序,什么意思呢?核心思想仍然是程序本身应该是可以自解释的,详细的可以看《源代码即设计》一文。在这里有两个重要的阶段,很多时候详细设计可以省略掉,我们的重要设计思路会体现到我们的程序注释中,再进一步很多垃圾无用的代码注释也要去掉,因为代码写好了,代码本身应该具备自解释能力。在源代码编写规范中谈到的注释,空行,缩进,变量命名,循环都有标准的编写规范,如果我们还能多考虑代码的复用和拆分,整个代码文件就能够有很强的可读性。
相关文章推荐
- 软件工程笔记之 – 另外一面
- 推荐电影(无剧透) -- Mr. Brooks(布鲁克斯先生) -- 人或多或少都有另外一面
- 第十五章 另外一面
- 人月神话读书笔记(15)----另外一面
- 一条长为L的绳子,一面靠墙,另外三边组成矩形,问此矩形最大面积能是多少?
- Foxmail 自动备份邮件,自动转发到另外一个邮箱的操作。
- oracle判断字符串中包函另外一个字符串
- 从一张表查询结果insert到另外一张表
- telnet的使用[简单的使用 其他的另外百度]
- 腾讯移动前端一面(不会的题)
- 百度互联网数据研发部电面:一面记录
- 启动另外的一个应用程序的Activity(三种方式)
- 把n个骰子扔在地上,所有骰子朝上一面的点数之和为S。输入n, 打印出S的所有可能的值出现的概率。
- 项目1——距离是一个点到另外一个点的距离
- 超越神话时时彩平台+Q【7133V5583】
- 京东PHP实习生(一面)
- mysql将一个表中的某一列复制到另外一个表的一列(联表更新,假如全部列)
- oracle复制一张表结构到另外一张新表中
- 一个Activity中打开另外一个Activity再返回的全部生命周期
- bat中调用另外一个bat