今天在CSDN上 看到这样一篇文章 (http://news.csdn.net/a/20100813/278141.html)看来后有些感想。大部分同学都坚持认为要写注释,但我写了几年后发现真正需要注释来帮助理解程序的地方是不是我们组织代码有问题呢?
我用C++3年，用C 3年，偶尔也用下java,读书的时候用是c++,工作后越来越用C，原因这里就不争论了，下面针对的是C语言来阐述可能会需要写注释的地方。
1:模块接口。
2:结构流程。
3:未完善或未来需求的分支。
4:核心算法。
也许还有，有些有交叉，我来一个个的分析为什么不需要或最少量的注释。
一:模块接口:模块接口是要求越少越好的注释，最好是0注释。原因有
1:请你用比注释更足以说明接口的函数或结构体作用的来命名，这样别人一看就知道，不需要看恼人的注释，我们发现大多数在版本升级中保留下的都是这样的接口。如果很偏，请考虑是否应该作为接口来公开给用户，思考自己的代码设计，有没有过度设计和给用户过大的使用自由度，因为适当的限制有利于控制bug,而不是一味的写注释。
2:参数，如果我看到参数类型的详细的说明注释，我们也得思考，连自己都要注释才能记得参数意义的函数参数我们是否值得把它公开给用户。
例如 int type类的参数，是否可以考虑用enum来枚举各个值的意义而代替恼人的注释呢？
3:过多的参数表明你的接口过于的繁杂，违背了kiss原则，是否可以考虑简单的接口参数呢？用简单代替注释，有助于大家写更清晰的模块接口，使得你的用户使用你的代码轻松愉快。相信我简单的接口往往是稳定的代码的最重要的特征。
4:过于生僻的函数参数是否意味着你的接口造了新的需要用户理解的概念，？能否拿掉减少用户的负担，使得使用更直观呢？
二 结构流程:
我们在写一个项目的工作机制的时候，比如媒体播放器，大家注释的地方都是数据经过的流程，结构的流程，其实当你在写注释的时候你长长的结构流程能够符合kiss 原则,有利于代码的稳定性吗？以mplayer的main函数为例，我想即使作者有详细的注释，我们看其来也很麻烦，那个main函数长的令人恐怖，如果还加上恼人的注释，我想没有人有勇气把这个函数看完。
当我们面对复杂的流程，较长的流程需要写注释的时候我们应该思考，是否我们的函数太长了，这个时候你把函数名作为你最好的注释，把长长的函数换成100行以内的函数吧，这样，你还需要注释吗？你的结构只会分层的清晰，长长的给你切分的非常合理。
三 未完善的未来的需求:
对于未完善的未来的需求我想大家更不应该写注释，对于未完善的分支，用assert(1==0),对于未来的需求，大家大可放心的删掉，不做一点的过度设计，如果不能满足未来需求，重写就是了，而我们的短小精悍的函数块，在下次重写中总是可以被复用，对于复用我认为不是复用框架，而是复用里面稳定的小函数块。因为框架的复用几乎是过度设计的开始。这个就是用C的风格组织代码。
这样我们还需要注释吗？
四 核心算法:
如果是一个核心算法的话，比如条码识别核心算法，对不起，这个时候更加不用写注释，原因有下面的状况:
1:一个核心算法的高手是不需要看注释来修改代码的，他面对的是核心的算法，而不是维护代码，他的思路会天马行空，改动会很大，才能达到最优的，而以前过时的都会被无穷的丢掉，以至于回头看他以前写的，都看不懂，但那些算法都以过时还有什么用呢？所以核心算法不需写注释的理由一应该是没有人反对的吧。
2:如果是核心算法，说真的，能称上核心的，能做到核心的都是高级程序员工作比较稳定，他们根本不需要注释。因为代码都是他自己来维护
3:核心算法涉及的bug并不如用户UI等那些多种操作来的多。写完稳定，几乎很难有bug,因为bug是与算法有关，很难有语言因素造成。
五，干净排列整齐的代码让人能愉快的工作，五颜六色的代码+注释，只会使得心情糟糕，这个还不说中国同学的蹩脚的英文注释。
让注释不成为复杂设计的理解手段，因为你要相信这个设计本身就有问题。
