[程序的长相] 之 注释君你很没节操

辛昕

[程序的长相] 之 注释君你很没节操 [复制链接]

以前写 程序该怎么写 这个话题多了，总是缺乏点感觉。
的确，说怎么写，确实不如剖析现在一般都怎么写的 来得实在。
楼主近期参考例程比较多，其中见到了不少让楼主 感慨万分 的代码，实在很想和大家分享。

所以从这个帖子开始，见到了什么新鲜长相，就贴图，加自己的评论，希望诸位有空看看。鲜花和板砖 都非常欢迎。

这是第一集，我们说的是 注释，闲话少说，先上图，我只想说，如果看到这样的注释，我只能说，注释君你太没节操了。

辛昕

关于这个截图，我有两点想吐槽。
1.注释君几乎是逢行便注释；
2.更该死的是，他用的是/**/块注释符号，而非//注释符号，而其实他的注释大多数都是一行（代码内部）

辛昕

写注释，是一个好习惯，应该说是一个非常敬业，非常专业，非常......勤奋的好习惯，相比于某些喜欢偷懒，一句注释都懒得写的人来说，这至少态度就非常专业和诚挚。

然而，这不代表 好 和 优秀。
我们仔细看里面的注释，代码内部那些，绝大多数，都只是对下面一行代码的解释。
然而，这种解释 是属于那种 重复一次代码在干什么 的内容。

其实，“解释代码在干什么”这种事情应该是 命名 的任务。
正名，如果名字不能说明自己在干什么，那这样的名字是没用的。

举个例子，那个Ioctl的调用，这种就是多余的。
宏已经明明白白说明了 打开RXON。 还要解释，打开接收允许，还说什么默认是关闭......这种事情我们一点都不关心；

还有一种重复注释，更是该死。
比如一个死循环等待 listen成功的。
在while上边已经有一句解释，永远等待listen.....额，这种解释还是会让人误解的。什么叫永远等待listen，还不如说 一直等到listen成功；
然后在循环内部尾处又加了一句 如果失败了，再listen一次。

这个短短的函数中还有一种注释更应该警惕。
就是函数开始的第一段注释。

它下面的事情是 toggleLED()，该死的是，它的注释写的内容是
关掉一个LED，表示已经进入监听状态；
当接收到信息时，LED会亮；

首先这段注释和这个toggleLED()调用是严重不对称的。
这段注释，如果加在函数体外，在函数名以前，会更加合适。

注释都是就近原则，既然他放在内部，又放在一句代码以前，人家就会认为这是解释 下一行代码的，可是，这其中完全看不到相关的内容。

对于这种注释，我只有一个建议：
取一个好名字，然后让所有注释都滚蛋！

忘了是那本书里写的，如果你需要在一行代码前加注释，那也许你更应该在这个地方抽离一个函数（然后，取一个好名字）。

从外观上看，在函数内部大量注释，肯定是不好的。

辛昕

就C和C++语言，有两种注释符号
// /**/
也许很多人没特别区别这两种符号。

如我所说，前者是 行注释，它的作用从开始到本行结束处；
后者是 块注释，括起来之处都在注释范围。

要特别注意的第一个地方是
和 代码块里的 ｛｝括号，以及预处理的条件判断符 不一样，块注释符号 是 不嵌套的。

这有什么呢？
麻烦大了！

我们在修改程序的时候，经常要屏蔽一些语句，整个函数，乃至一片函数群。
如果像上图这样，充满了 块注释符号，那么，哪怕是一个简单的函数，你都很难通过一个 块注释符号，把它注释掉。

因为，它会和遇到的下一个块注释符号 的 右半边组成一个 注释快，而显然，你的目的是要把所有的函数代码注释掉。

这种过程会造成很麻烦的一个一个改掉，假如你选择了不恰当地方法，还会造成当你想重新打开注释掉的代码时又要经历一次几乎相同的麻烦操作。

在某些情况下，这还会引起很多麻烦。
比如说，这个函数体比较长之类的。

这不是一个小问题。

Steve McConnel 在 代码大全 里说，不管采取什么样的注释风格，如果造成修改困难，那这种注释风格就很糟糕。

我想，上面我提到的，块注释符号不嵌套带来的麻烦，算是上 这句话的一个不错的佐证。

选择块注释符号，而非行注释符号，这是因为，块注释符号，可以让你后续非常轻松地在里头添加 注释语句，而无需再打一个注释符号，甚至忘了，造成编译错误

这种不慎错误，会造成 死板的编译器产生几十个上百个甚至几百个编译错误，会给人造成一定的心理紧张。

当然，块注释符号自有其用处，但是，在某种情况下，即使你有非在函数内部注释的必要，也请尽可能选择 行注释符号，因为这样的注释内容一般来说不会太多，如果让代码充斥 块注释符号，这一部分代码将变得极其难收拾。


                       第一集 END

soso

又看到了辛昕手记  呵呵

cawyai23

小白向版主学习