4 注释

别给糟糕的代码加注释——重新写吧
若编程语言足够有表达力 或者长于用这些语言来表达意图 就不那么需要注释
注释的恰当用法是弥补我们在用代码表达意图时遭遇的失败
程序员并不能坚持维护注解 代码在变化 在演化 注释并不总是随之变动
只有代码能忠实地告诉你它做的事 那是唯一真正准确的信息来源 该多花心思尽量减少注释量

注释不能美化糟糕的代码

写注释的常见动机之一是糟糕代码的存在
与其花时间编写解释你搞出的糟糕的代码的注释 不如花时间清洁那堆糟糕的代码

让代码来阐述

只需要创建一个描述与注释所言同一事物的函数即可用代码解释你大部分的意图

// Check to see if the employee is eligible for full benefits
if ((empoloyee.flags & HOURLY_FLAG) && (employee.age > 65))

=>

if (empoloyee.isEligibleForFullBenefits())

复杂的 if 语句应该用函数来表达 不要让后来者去研究代码看你是想过滤什么信息 可读性和可执行性一样重要

好注释

唯一真正好的注释是你想办法不去写的注释

法律信息

只要有可能 就指向一份标准许可或其他外部文档 而不是要把所有条款放到注释中

提供信息注释

// Returns an instance of the Responder being tested
protected abstract Responder responderInstance();

用函数名称传达信息

protected abstract Responder responderBeingTested;

// format matched kk:mm:ss EEE, MMM, dd, yyyy
Pattern timeMatcher = Pattern.compile("\\d*:\\d*:\\d* \\w*, \\w* \\d*, \\d*");

移到某个转换日期和时间格式的类中 辅以一个恰当的函数名 就不需要注释了

意图声明注释

涉及不太容易理解的代码设计时 需要辅以简短关键的解释

阐释

除非是不能改动的标准库的一部分 否则尽量用恰当的名称代替要标记的注释语义

警示

@Ignore 关闭测试用例

@Ignore("Takes too long to run")

public static SimpleDateFormat makeStandardHttpDateFormat() {
	// SimpleDateFormat is not thread safe, so we need to create each instance independently
	SimpleDateFormat df = new SimpleDateFormat("EEE, dd MMM yyyy HH:mm:ss z");
	df.setTimeZone(TimeZone.getTimeZone("GMT));
	return df;
}

线程安全警示 阻止以效率之名使用静态初始器

todo注释

需要定期检查 删除不再需要的

放大

放大看来不合理写法的重要性

// the trim is real important. It removes the starting spaces that could cause the item to be recognized as another list.
String listItemContent = match.group(3).trim();
...

公共 API 中的 JavaDoc

要注意的是 JavaDoc 也可能误导 不适用 或者提供错误信息

复杂算法

如果晦涩难懂的算法还是建议可以在前面用注释解释的 省去读者去读具体算法的精力

坏注释

大多数注释都属此类 坏注释都是糟糕代码的支撑或接口 或者对错误决策的修正 基本上等于程序员自说自话

多余注释

简单函数头部位置的注释全属多余 读这段注释花的时间没准比读代码花的时间还要长

误导注释

循规式注释

所谓每个函数都要有 JavaDoc 或每个变量都要有注释的规矩全然是愚蠢可笑的 这类注释徒然让代码变得散乱

日志式注释

全部删除 因为源代码控制系统的存在

废话注释

JavaDoc 可能也是废话

能用函数或变量就别用注释

去掉注释 换成语义化变量和函数

位置标记

// Actions /
实属无理 鸡零狗碎 理当删除 只在特别有价值的时候用

括号后面的注释

			} // while
		} // try
	} // catch

如果你发现自己想标记右括号 其实应该做的是缩短函数

归属与署名

/* Added by Rick */
全部删除 因为源代码控制系统的存在

注释掉的代码

注释掉的代码堆积在一起 就像破酒瓶底的渣滓一般
全部删除 因为源代码控制系统的存在

非公共代码中的 JavaDoc

不打算作公共用途的 JavaDoc 完全是无用的 其形式与八股文无异