注释 —— 《clean code》读后感

     注释并不一定都是好的，事实上，在实际开发过程中，注释还很可能是坏的。因为代码可能一直在变，在多久以后，代码也许已经面目全非，而工程师往往只顾改代码，却并不会去同步更新注释。注释可能在腐化的过程中，变得越来越名不符实，给工程师以错误的向导。也正是因为如此，如果注释做得不好，往往还会失去注释的意义，迫使工程师不得不每次都重新过代码，不相信满嘴谎言的注释。

     高质量的注释有以下原则：

1）不要依赖注释，更好的做法是提高代码的表达能力——好的命名，简短的函数都可以帮助做到。如果能用改善代码的方式解决的，都不要用注释去解决。什么也不会比乱七八糟的注释更有本事搞乱一个模块，什么也不会比陈旧、提供错误信息的注释更有破坏性。真实可靠的地方只有一个：代码。

2）注释不能美化糟糕的代码。别给糟糕的代码加注释——重新写吧。

3）不要给复杂的代码配以注释，干脆把代码封进一个短小的函数里，然后给函数起一个清晰易懂的名字。

不好的：

// check to see if the employee is eligible for full benefits

if((employee.flags & HOURLY_FLAG) && (employee.age>65) )

好的：

if(employee.isEligibleForFullBenefits())

如果是ruby这种可以带谓语的语言，你甚至可以给断言加?号。

4) 好注释包括哪些呢？ 法律信息这种必须有的注释、对复杂代码实现方法的解释（解释你的意图）、警示（非常重要的地方，加以提醒）。

5）不好的注释呢？ 喃喃自语（含糊不清，完全写给自己看的，别人很难看懂的）、多余的注释（从代码上一眼就能看出作用的注释，完全是废话）、误导性注释、注释信息过多

6）有些注释我们可以利用版本控制软件完成，没必要在代码中再表现了。例如：代码的最后修改时间，修改的人，修改的地方等等。

转载于:https://www.cnblogs.com/cly84920/archive/2010/03/29/4426812.html