《Clean Code》学习之—Comments

        学习《Clean Code》也有一段时间了，这本书写的真的不错。这不，作者又将眼光对准了注释。回顾这一年的编程生涯，对注释的注意确实不是很多。

        在公司的编码规范中，对注释有一些要求，但是要求不是很高。在之前的观念中，觉得注释无非是在代码写得比较挫的地方给一些解释，让以后来看的人能够明白代码的逻辑。但是这一年来很明显的感觉是，随着迭代的增加，注释能给予的信息原来越少。比如代码一直在改进，可能注释还是一成不变，导致注释不能给我们足够的信息，甚至给我们错误的信息。对这一块，印象比较深，也吃过亏。在本章中，作者也提出了不少自己对于注释的观点，下面就来看看他都说了些什么。

        “Don’t comment bad code – rewrite it” –Brian W. Kernighan and P.J.Plaugher

         没有东西比正确放置的注释更有帮助，也没有东西比断章取义的注释使代码更混乱。

        使用注释的目的：The proper use of comments is to compensate for our failure to express ourself in code.（使用注释主要是用来弥补我们在代码上的不足）

        注释使用得不好的危害：Inaccurate comments are far worse than no comments at all.（不准确的注释远比没有注释要糟糕）

        为什么不建议使用注释：Truth can only be found in one place: The code. Only the code can truly tell you what it does.（真相只存在于代码之中，只有代码才能真正告诉你它在做什么）

        1.Comments Do Not Make Up for Bad Code（注释不能弥补代码上的不足）

        One of the more common motivations for writing comments is bad code. We write a module and we know it is confusing and disorganized. We know it’s a mess. So we want comment it, bu what we really need to do is cleaning it.（很多人写注释的理由是代码写得太挫，其实代码很挫的时候我们需要的不是注释，而是重新整理它--重构）

        2.Explain yourself in code（用代码来表达自己）

一，好的注释

       3.Explanation of Intent（解释意图）

        Sometimes a comment goes beyond just useful information about the implementation and provides the intent behind a decision.（有时候，注释不但给予关于当前操作的有用信息，而且表明某项决定后的意图）

        4.Clarification（澄清）

        有时候为了使参数和返回值的意思更加明确，但是我们又不能添加代码的时候（比如在lib中），这时候用注释来澄清就很有用。

        5.Warning of Consequences（对结果进行预警）

        有时候有必要就某一个结果给其它程序员一些警示。

        6.TODO Comments

        有时候留下TO Do注释也是很有必要的，to do注释能告诉人们为什么函数的运行效果不佳，以及这个函数将来从哪些方面改进。

        7.Amplification（放大）

        A comment may be used to amplify the importance of something that may otherwise seem inconsequential.（注释有时候用来放大那些看起来不重要的东西的重要性）。

二，不好的注释

        8.Mumbling（含混不清）

        9.Redundant Comments（冗余的注释）

        10.Misleading Comments（误导性的注释）

        11.Mandated Comments（强制注释）

         有时候可能会强制要求对每个方法每个变量都要注释，这其实会使得代码很迷惑并且缺乏组织性。

         12.Journal Comments（长篇大论式的注释）

        13.Noise Comments（类似噪音的注释）

         有时候对于意思很明显的函数也注释，这些注释不能带来任何新的信息，很令人讨厌。

       Don’t use a comment when you can use a function or a variable.（不要在你能够使用函数或变量的地方使用注释）

        作者还谈到了其它方面的注释，比如Html格式的注释等等，这些对于我们平常的代码影响也不是很大，一般我们也不会吃饱了撑着去弄那种注释，这里就不再赘述了。

        总之，通过本章的学习，我们要意识到：尽量不要使用注释，这并不表示不用，而是在你想使用注释之前多想想，是否存在修改代码而不是使用注释来使代码更具可读性的可能。