第四章 注释
其实,注释的存在在某种方面是一种失败,因为在这个时候我们无法用代码来表达意图或者表达的不准确,若程序有足够的表达力,就根本不需要注释。
为什么要这样说注释呢?
代码总是在不停的演化,重构,注释存在的时间越久,就离其所描述的代码越远,越来越不准确,它会提供错误的信息,这时候它的破坏力是难以估计的——它们满口胡言,它们预期的东西永不能实现,它们设定了无需也不应遵循的旧规则。
为什么?程序员不能坚持维护注释
注释的恰当用法是弥补我们在用代码表达意图是遭遇的失败。别给糟糕的代码加注释,重新写吧
如何解决?
代码是唯一真实而且准确的东西,它忠实的告诉你你做的事情。
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,函数头
短函数不需要太多描述,长函数的话好好的起个名字吧,比写函数头注释要好的多
如果我们需要注释的时候,我们应该想想,什么应该写,什么注释不该写,我们要尽量用代码来表达,每次写注释的时候,我们都要审视自己,感受自己在表达能力的失败并改正。