clean code 之注释规范

                                                                第四章   注释

 

      其实，注释的存在在某种方面是一种失败，因为在这个时候我们无法用代码来表达意图或者表达的不准确，若程序有足够的表达力，就根本不需要注释。

 

为什么要这样说注释呢？

 

代码总是在不停的演化，重构，注释存在的时间越久，就离其所描述的代码越远，越来越不准确，它会提供错误的信息，这时候它的破坏力是难以估计的——它们满口胡言，它们预期的东西永不能实现，它们设定了无需也不应遵循的旧规则。

 

为什么？程序员不能坚持维护注释

 

注释的恰当用法是弥补我们在用代码表达意图是遭遇的失败。别给糟糕的代码加注释，重新写吧

 

如何解决？

 

代码是唯一真实而且准确的东西，它忠实的告诉你你做的事情。

 

 

1，注释不能美化糟糕的代码

 

写注释的常见动机之一是糟糕的代码的存在，我们写一块模块，但是结果却不尽人意。于是，我们告诉自己说，写点注释吧。。。。。

 

带有少量注释的整洁而富有表达力的代码，要比带有大量注释的零碎的复杂的代码像样得多，与其华时间写出糟糕的代码的注释，不如花时间清洁你的代码

 

2，用代码来阐述（重构你的代码）

 

3，好注释

 

有些注释是必须的也是有利的，不过真正好的注释是你想办法不去写的注释

 

a,法律信息

 

公司代码规范要求编写与法律有关的注释（版权，著作权声明）写在开头

 

//Copyright (C) 2003,2004,2005 by Object Mentor, Inc.All right reserved.
//Released under the terms of the GNU General Public License version 2 or later

 

b，提供基本信息，或对意图的解释。

 

（提供作者思路）但更好的办法是利用函数名称来传递信息。

 

c阐释

 

（可能读者难理解的东西）或者放大某种看起来不合理逻辑的重要性

 

//打印当前时间中的一段代码
var dateDigitToString = function (num) {
        return num < 10 ? '0' + num : num;
    };//这个函数的作用是把个位数的十位置0,凑成两位数，如：08 04（这个注释清晰的表达了function的作用，可能怕初学者不懂什么意思）

 

风险：解释不清楚，确认注释的正确性很麻烦，更好的方法是尽量让你的程序足够清楚

 

d，警示

 

警告其他程序员会出现某种后果或原因。

 

e，TODO注释

 

TODO注释是程序员认为应该做，但由于某种原因还没做的工作，但它不是在系统中留下糟糕代码的借口，所以你要定期查看，删除不再需要的

 

 

 

4，坏注释

 

通常，坏注释都是糟糕代码的支撑或借口，如果你觉得应该或者因为过程需要添加注释，那是无谓之举，如果要写，就要花必要的时间写出最好的注释

 

5，多余的注释

 

简单的东西没必要添加注释，写一段程序之后，注释并不能提供比代码更多的信息，而且比程序来说又不如代码精确，读者理解有误的话，会误导读者，或者联系不明显，也会误导读者

归属或署名——随着代码重构，会越来越不准确

 

 

a，日志式注释

 

有人会在写代码之前，在模块开始的时候添加注释——日志型注释。现在没有必要

 

b，注释掉的代码

 

其他人会想，代码放在那里一定有它的意义，很重要，不能删，应该删掉

 

c，信息过多（废话多，可以精简）

 

d，函数头

 

短函数不需要太多描述，长函数的话好好的起个名字吧，比写函数头注释要好的多

 

如果我们需要注释的时候，我们应该想想，什么应该写，什么注释不该写，我们要尽量用代码来表达，每次写注释的时候，我们都要审视自己，感受自己在表达能力的失败并改正。