《代码整洁之道》第四章 注释

概述

什么也比不上放置良好的注释来得有用。什么也不会比乱七八糟的注释更有本事搞乱模块。什么也不会比陈旧、提供错误信息的注释更有破坏性。

注释并不像辛德勒的名单。它们并不“纯然地好”。实际上,注释最多也就是一种必须的恶。若编程语言足够有表达力,或者我们长于用这些语言来表达意图,就不那么需要注释——也许根本不需要。

注释的恰当用法是弥补我们在用代码表达意图时遭遇的失败。

注释存在的时间越久,就离其所描述的代码越远,越来越变得全然错误。原因很简单。程序员不能坚持维护注释。

不准确的注释要比没注释坏得多。它们满口胡言。它们预期的东西永不能实现。它们设定了无需也不应再遵循的旧规真实只在一处地方有:代码。只有代码能忠实地告诉你它做的事。那是唯一真正准确信息来源。所以,尽管有时也需要注释,我们也该多花心思尽量减少注释量。

1. 好的注释

有些注释是必须的,也是有利的。来看看一些我认为值得写的注释。不过要记住,唯真正好的注释是你想办法不去写的注释。

1.1 法律信息

有时,公司代码规范要求编写与法律有关的注释。例如,版权及著作权声明就是必须和有理由在每个源文件开头注释处放置的内容。
eg:

1.2 提供信息的注释

有时,用注释来提供基本信息也有其用处。例如,以下注释解释了某个抽象方法的返回值：

这类注释有时管用,但更好的方式是尽量利用函数名称传达信息。

1.3 对意图的解释

有时,注释不仅提供了有关实现的有用信息,而且还提供了某个决定后面的意图。这类进场出现在方法中，表示我这一步代码的意图到底是什么。
eg:

public void test(){
   
   
...
	for(Student student:studentList