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

初级代码游戏的专栏介绍与文章目录-CSDN博客

我的github：codetoys，所有代码都将会位于ctfc库中。已经放入库中我会指出在库中的位置。

这些代码大部分以Linux为目标但部分代码是纯C++的，可以在任何平台上使用。

 

---

        昨天（注：这是重发的）写了篇“程序员为什么不写注释？因为毫无意义啊！-CSDN博客”，竟然有人表示赞同，我的内心是很有波澜的。

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

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

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

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

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

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

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

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

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

        看看下面这句代码，需不需要注释？

#define PI 3.14

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

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

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

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

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

x += y/3.;

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

x = y/3;

        能编译吗？当然能。

        能理解吗？当然能——但是，还是原来的意思吗？

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

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

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

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

总结：

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

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

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

（这里是结束）