posts - 56, comments - 54, trackbacks - 0, articles - 4
   ::  ::  :: 联系 :: 聚合  :: 管理

软件开发的评价标准（转载）

Posted on 2005-11-16 16:40 Terry的Blog 阅读(1102) 评论(1)  编辑  收藏 所属分类: 软件工程
三、注释与文档

首先讨论一个计算工作量的数学模型。

1.没有注释的情况下：
第一次开发工作量＝代码行数×单位代码工作量
维护工作量＝理解代码工作量＋决定方案工作量＋修改代码行数×单位代码工作量

2、有注释的情况下：
第一次开发工作量＝代码行数×单位代码工作量＋代码行数×注释率×单位注释工作量
维护工作量＝基于注释理解代码工作量＋决定方案工作量＋修改代码行数×单位代码工作量＋修改代码行数×注释率×单位注释工作量

增加注释之后，增机了注释的工作量，这些增加需要通过节约理解代码的工作量赚回来。

3、理解代码的工作量讨论
在没有注释的情况下：
理解代码工作量＝代码总量×理解代码的效率
在有注释的情况下：
理解代码工作量＝注释总量×理解注释的效率
又因为
注释总量＝代码总量×注释率

因此，要想通过注释减少维护工作量，就要切实降低注释率，并且提高注释的效率。

4、这些数据的含义

注释率：软件的注释行数/软件的程序行数

有人像这样写代码
java代码: 
//给i赋初始值
int i=10;
//开始循环
for(int j=0;j<i;j++){
//输出j的值
System.out.println(j);
}//循环结束
这样的一比一注释，注释率就是1。一般来说，注释率大于1的程序，肯定是垃圾。因为写这个程序的人，根本不知道该注释哪些地方。

但是，并不是说注释率越低越好，因为注释少了之后，可能会影响理解注释的效率。

面对一次维护需求时：
理解注释的效率：需要阅读的注释行数/注释总数

如果一个维护者，在阅读了所有的注释之后，还没有理解程序，更不要说找到解决方案，那么他就必须去阅读代码。理解代码的工作量，就是没有注释时的工作量再加上被垃圾注释浪费掉的工作量。

这时的理解注释的效率，就是大于1的。写出这样的注释的人，不配做程序员。

切实提高理解注释的效率，是提高维护效率的根本。可以有以下手段：
1、结构化文档
2、HTML格式的合理的超链接
3、关键字索引（方便对于注释全文检索）
4、逻辑清晰的概要介绍

上面的这些公式都有一条：决定方案工作量。
这个工作量其实是可以合并的。以往的理解是，必须理解了现有的程序，才能决定维护的方案。但是我们可以假设，如果通过查询注释和文档，就能找到如何维护的答案，那么这样的维护就是最轻松的。

我们不假设所有的维护都能通过查询注释和文档，直接得到答案，但是如果有一个预先的合理的考虑，而写下了系统维护指南这样的文档，那么这样的文档，将是最有价值的。

另外一个手段，就是在每次维护之后，写下一个维护记录，大致格式是：
我的维护需求，我查询了哪些注释和文档，最后我在哪里找到了答案

这样的记录，将会为后来者提供极大的方便。

下面说一点题外话，因为在软件工程中，还存在这样的文档：
《功能需求描述》《概要设计》《详细设计》《.......》
我不理解为什么需要这样的文档，也不理解谁会来阅读这样的文档。为了模仿建筑工程，软件工程已经大大的扭曲了自己的本性。

注释与文档的本质，是为了便于软件的开发和维护，而不是在一道一道的工序之间作为“交接班”的说明。

如果一份文档，无法回答这两个问题，那么这份文档就是浪费了：

谁愿意写这样的文档？

评论

# re: 软件开发的评价标准（转载）  回复  更多评论   

2011-05-12 17:16 by 爱米
下面说一点题外话，因为在软件工程中，还存在这样的文档：
《功能需求描述》《概要设计》《详细设计》《.......》
我不理解为什么需要这样的文档，也不理解谁会来阅读这样的文档。为了模仿建筑工程，软件工程已经大大的扭曲了自己的本性。

——显然你肯定还没有参与大型的团队项目，所以有这样的疑问也不奇怪。
文档不仅仅是交接，而是思想的直接表达与传承方式。

只有注册用户登录后才能发表评论。
网站导航: