原文链接：
英文原文链接：
我很赞同这篇文章的观点。尤其对于第一第二种注释，有段时间我是深恶痛绝，遇到必先除而后快；后来麻木了，有时还迫不得已添加这种注释，但我还是尽最大努力去避免。看了评论，发现有人根据他们的项目经验，得出那两种注释有益的论断，我不很理解。
我结合我的经历谈一下感受：当我刚进公司的时候，接手的代码让我头痛眼花，当中就充斥着大量的注释了过时代码，弄得版面很烦乱，让我读起代码来理不清思路，抓不住重点。当时，我还不懂版本管理，但觉得这种做法很不妥：有谁想看到代码里到处是过时的、没用的甚至是错误的屏蔽代码段？有人说这是为了让人看到程序更改的过程，理解修改的思路。但自从使用了版本管理工具后，就体会到这种说法靠不住脚。代码行或者代码段的变更，能简单地用注释旧代码来表达清楚吗？有时候更改是频繁的，有时候更改时反复的，这可能牵涉到需求分析等其他方面，但可以推想，随着修改次数的增加，代码里这种旧片段将越来越多，可读性变差，这时候或许需要对这些旧片段进行整理和维护。这里的工作量不见得比编码小，否则这里的注释的正确性、严谨性和完整性将受到影响。扯了这么多废话，其实我就想说：为啥不把这些交给版本管理呢？注释了的过期代码能有版本库记得详细？如果我当初能得到代码变更的版本管理信息，我能更快地熟悉代码的结构流程和设计思路，而且良好的log meassage能让我更好地理解每次的修改。所以，不再犹豫，果断地删去过期代码吧。
至于代码行间留下的“姓名 日期”注释，刚开始我也认为是很好的习惯和风格。不过，在实践当中会发现不少问题，是不是我改动过的每一行都应该加这样的注释呢？显然不现实，也不妥，尤其是代码块代码段的增删修改。用带有起始、结束标志的注释进行说明吧，然而当出现不同人交叉修改时，会变得混乱不堪。更严重的是，如果有一个人不遵循这样的要求，修改过而不留“痕迹”，那么所谓根据注释来寻找相关负责人就是扯淡。同样的，版本管理工具也解决了相应的问题，基于用户设置，谁在什么时候对那里进行了怎样的修改，blame一下就一目了然。现在我在实践中只有极少情况留这样的注释，那就是修改没经过充分测试验证(在工程化角度看这其实是错误的危险行为)或者以我当前的水平我认为我对该段代码的理解有很大的局限性，而我需要为它增加说明注释时(最大限度减少误导)。
总的来说，我认为这两种注释习惯的出发点都是很有益而值得提倡的，它反映了程序员对维护代码的一种良好意识和对编程工作的一种良好态度；可是在有更方便更自然的工具的情况下，这些做法无疑增加了代码的维护成本，对项目而言是不利的。因此，我对那些认为这两种注释有益的网友不很理解：拥有不少项目经验的他们应该知道版本控制吧，既然原文也提到“交给版本控制”，为何还指出项目需要这两种注释？是因为他们项目实践证明不适用版本控制，还是有其他与版本控制无关的更深层的原因？恕我见识有限，无法理解。
后记：
在我实习转正时，我实习期改过的代码需要交给所谓“评测部”进行代码走查，他们给我的意见是“为什么没有标记哪些模块、函数是你做的？”，我说我没有增加，只做了修改；那“为什么没有修改的注释？”，我说在版本库有记录和清单，导出了一份发过去，答复是"看不懂"，然后不了了之。公司的svn服务器很少人用，原来维护管理的人听说离职了，这或许是个典型的软件作坊的真实写照。
此外，我个人对文件头注释里的“修改人/日期/内容”不感冒，这也是增加维护成本，而且修改多了这个列表就长得可笑；当然不排除某些IDE能够自动添加，或者是用vi、emacs的牛人自己设定的宏(宏?忘了叫啥，反正也是自动添加格式的东东)，维护起来很方便；加上代码折叠，这样的注释倒是挺好的。不过这也正说明了强大的工具解放了生产力，使其用在更需要的地方；想让注释承担起完整描述需求变更、设计修改、人员权责、缺陷跟踪等等这么繁重的任务，它不好做，也不该做。
谈到注释，我突然想起我下载了doxygen但还没开始用，想想维护一份可读性好注释的同时也毫不费力地维护了一份可读性好的文档，这该多惬意啊
阅读(1200) | 评论(0) | 转发(0) |
