反例

反对给代码写注释的人认为，“代码应该好到不需要任何多余的解释”。好的代码确实不需要注释来描述变量或函数是干什么用的。

// bad start:
int a = 4 * OFFSET;
// but don't use a comment to tell what it does:
int a = 4 * OFFSET; // initial foo value
// instead choose a name telling it itself:
int initial_foo = 4 * OFFSET;

确实，有意义的变量名根本不需要注释，但这实际上更像是一种体面的编码风格，而不是文档。当这种片面的观点变成反对使用代码注释的普遍理由时，问题就出现了。

问题是，即使变量、方法、类、函数、模块的名称是自解释的，但这些并不能描述出代码的全局面貌，也不一定能说明各部分代码为什么要那么写。当然，清晰的实现往往会让我们产生一种错觉，认为不需要再写注释了。当你花了几个小时甚至几天时间解决了手头的问题，那些代码在当下可能是完美的，然后你把它们打包、提交。