你有没有这样的经历:别人审查过你的代码之后给出的注释,你认为是没有必要的?注释代码是为了提高代码的可读性,目的是为了能让其他人更容易理解你的代码。
我特别讨厌这5种注释类型以及制造它们的程序员。希望你不是其中之一。
这个程序员自认为写了一段很了不得的代码,所以觉得有必要用自己的名字对每行代码进行标记。实施版本控制系统(VCS)能实现对代码变更的问责,但是也不会这么明显知道谁应对此负责。
如果一段代码已不再使用(即过时),那就删除它——不要浪费时间给这些代码写注释。此外,如果你需要复制这段被删除的代码,别忘了还有版本控制系统,你完全可以从早期的版本中恢复代码。
我们都知道基础的编程逻辑是如何工作的——所以你不需要多此一举来解释这些显而易见的工作原理,虽然说你解释得很happy,但这只是在浪费时间和空间。
如果你一定要在注释里提及需求,那么不要涉及别人的名字。销售部门的Jim可能会离开公司,而且很有可能大多数程序员根本不知道这是何许人也。不要在注释里提及不相干的事实。
这种类型的注释包含了上面所有其他类型。如果是在项目的初始开发阶段,这种待做注释是非常有用的,但如果是在几年后的产品代码——那就会出问题了。如果有什么需要修复的,立马解决,不要把它搁置一边,“以后再做”。
如果你也常常犯这样的注释错误,如果你想了解注释的最佳做法,我建议你阅读类似于Steve McConnell写的《Code Complete》这样的好书。