程序员为什么不写注释?因为没有软件工程

        昨天写了篇“程序员为什么不写注释?因为毫无意义啊!-CSDN博客”,竟然有人表示赞同,我的内心是很有波澜的。

        “写注释”确实不是编程语言必须的要求,注释本身仅仅是代码的“文档”。

        可是,为什么所有的编程语言,甚至包括脚本语言,比如shell脚本、批处理文件,以及大部分配置文件格式,都支持添加注释呢?

        这足以可见,添加注释是一种内在的、本能的要求。当然,在没有强制要求的情况下,确实是靠自觉的。而且,必须承认,大部分人是缺乏这种自觉性的。

        对注释的强制性要求的法律基础来自质量管理体系和软件工程规范(质量管理体系和软件工程规范在软件工程领域是相同的,不同的标准制定方而已,可以互相引用,比如有一次做ISO9001认证,考官手里拿的就是国家软件工程规范)。

        所有的质量管理体系的基础和核心就是一句话:

        “说你所做的,做你所说的”。

        这句话就写在ISO9001培训手册的封面上,理解了这句话,就理解了“质量管理”的精髓。

        字你都认识,意思你也懂,但你未必理解正确了。质量管理并不是自然而言的东西,反而是违背直觉的。

        大部分人都认为,足够简单的、显而易见的、众所周知的东西是不需要注释的——这看起来自然而然、理所应当,然而这违背了上面这句话,“说你所做的,做你所说的”,而你只做没有说。

        看看下面这句代码,需不需要注释?

#define PI 3.14

        这句代码足够简单,基本上一眼就能看出来,这是定义了圆周率为3.14。大部分情况下,确实想不出来这句话能加什么注释,但是我们仍然能尝试提出一些问题:

  • 这个值的精度为什么是小数点后两位?改成3.1415926行不行?

        如果PI的意思确实是圆周率,那么似乎是可以改成3.1415926的,但是,这会导致计算结果与预期不同,尽管你觉得这样更精确,但是所有预设的测试将无法通过。

        所以,假设这是一个严肃的项目,这个值必然是在文档里明确说明的(注释也属于“文档”的一部分)。如果你不在乎别人怎么想,当然不需要任何说明。

        再看看这句代码要不要加注释:

x += y/3.;

        这句代码也够简单,运算符“+=”我们很熟悉,数字后面加个“.”的目的我们也很清楚,看起来确实没什么必要加注释了。但是如果无意中删除掉了"+="的“+”或者“3.”的“.”,变成了这样:

x = y/3;

        能编译吗?当然能。

        能理解吗?当然能——但是,还是原来的意思吗?

        如果这里有个画蛇添足的注释:“x需要增加y的三分之一,注意要转为浮点数做除法”,虽然不是太懂这个算法,但是很容易看出来这行代码和注释不一致吧?

        这才是质量保证的基础和核心:你的所作所为必须有一份参照,通过与参照比较是否一致来确认你的工作符合预期

        这里没有提及正确性,那么正确性在哪里?工作地目的难道不是为了正确性吗?

        这就涉及到质量保证的另外一部分:评审。即通过对文档的审核来保证正确性

总结:

        文档(注释)用来保证你做的和你的想法一致。

        而你的想法是否正确,是评审的责任。

        不写注释的程序员,是因为没有在软件工程的管理之下。

(这里是结束)

你可能感兴趣的:(设计,抱怨与漫谈,软件开发,软件工程)