关于代码注释我的个人看法

转自：http://www.oschina.net/question/249672_45415

也针对代码注释，发表下我的个人意见。

我个人，就代码注释，经历过一下几个阶段。

1、不写。刚学会编程语言，特别是感觉”精通“的阶段，下笔如有神。非常鄙视要前期图纸上规划系统。

这个阶段，现在一些小朋友也有，总结下来我觉得也不能全怪曾经的我和这些小朋友。根本原因是由于缺乏项目经验，和缺乏实践经验，导致对于问题或设计目标的理解过于片面，只是集中在局部问题上。而由于对用编程语言存在一定的自信，使得一个局部问题用代码描述，好过任何一个文字的描述。其实对于局部代码而言，这是事实。

2、强迫自己写。因为规模复杂后，我自身出现一个问题，现在的小朋友也存在。稍微复杂的点程序就搞不定了。这边问题解决，那边出现问题了。代码得反复看，而且还要深入理解。累啊。想不写注释，在DEBUG时，也会自己加，恨不得把一个函数，输出的值（如果可能的话）都列出来，省得再分析。最后养成了代码设计书写习惯，和强迫注释的习惯。至少一目了然。

这个阶段挺难突破的，如果不从理论上提高自己，包括多进程编程，模块化编程，面向对象编程等思想的提升，但不要扯什么三层架构，MVC的概念倒算理论。

3、只注释歧义性或潜在问题或阶段性注释。现在写代码，通常先抽象设计目标的模型，然后选择架构方式，再逐步细化。

每个阶段的设计目标不一样，为了衔接每个阶段的开发，会有注释，通常在下一个阶段这些注释，晃眼睛，我也就删除掉了。但有时为了保证架构的可对应（代码与设计方案），还会保留。

同时，会，可能存在歧义的地方，给予注释。这样在后期阅读代码时，可以grep到信息。方便理解。不过这个通常都是全局的东西。局部的东西，仍然是用代码来描述设计逻辑。局部代码写注释，我是不会干的，要么我改进我的代码书写方法，方便阅读，要么你改进你的语言水平提高阅读能力。

另一个注释的地方，是留BUG的地方。准确说不叫BUG。叫做不支持。或有些工作没细化做完。例如假设用户极少发生一种数据输入组合，甚至这种组织只是在理论上成立，那么对于这种情况的响应，我通常直接error掉。但这个error掉，并不代表是正确的处理意见。之所以不做，是从投入产出比考虑。

工程的东西，和理论的东西不一样。一个事件有没有意义，在于是否被客户使用发生。如果客户永远不会发生，你就不需要去折腾。因为你创造的东西，有没有价值是用户说的算的。有些情况，理论上存在，工程上是极小概率存在，此时你过多的精力关注它，会令整体系统更差，因为你的精力是有限的。在这种问题不确定重要级别的情况下，那就用注释，列清楚计划或风险，看以后是否需要更改。

因此，目前我对注释的作用是三个：

1、开发过程中，不同阶段，代码设计衔接时的注释，包括团队协同开发的接口问题，和自身开发版本更替信息。

2、全局存在歧义的东西。

3、遗留的后门或BUG。