代码自解释不是不写注释的理由.docxVIP

代码自解释不是不写注释的理由 反对给代码写注释的人认为，“代码应当好到不需要任何多余的解释”。好的代码的确不需要注释来描述变量或函数是干什么用的。 //?bad?start: int a = 4 * OFFSET; //?but?dont?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; 的确，有意义的变量名根本不需要注释，但这实际上更像是一种风光的编码风格，而不是文档。当这种片面的观点变成反对使用代码注释的普遍理由时，问题就消灭了。 问题是，即便变量、方法、类、函数、模块的名称是自解释的，但这些并不能描述出代码的全局面貌，也不肯定能说明各部分代码为什么要那么写。当然，清楚的实现往往会让我们产生一种错觉，认为不需要再写注释了。当你花了几个小时甚至几天时间处理了手头的问题，那些代码在当下可能是完善的，然后你把它们打包、提交。 但是一个月后会怎样？你能记住多少细节？它们还是那么有意义吗？ 软件开发困难重重 当然，有人可能会争辩说：“代码就在那里，你看一下就明白了”。假如我们说的是某块代码是干什么用的，那么或许这么说是有道理的。但对于任何超出这个范围的东西，深挖代码可能是在铺张时间，就像在阅读一本没有索引的书，你要从头读起，才可能找到你需要的东西。 而且，这不只仅是为了了解别人的代码，或者向别人解释你的想法。当你重新查看旧代码或者修复错误时，你的脑子里是不是经常犯嘀咕，或者由于 git blame 显示了你的名字而感到惊异？然而，再往后，它们可能被忘得一干二净，然后你会再次信任一切都应当是自解释的，全部的细节都应当是明确无误的。 无论你怎样努力，软件本身并不会完全自解释。这既不是你的错，我也不是想要质疑你的力量，这与人类本身有关，我们低估了软件的简单性，而且人类的思维具有波动性。注释的目的不是为了指出代码中存在的缺陷，而是为了抵制编程言语本身存在的缺点。即便是最洁净的代码也不行能本人解释写代码的人在写代码时在想些什么。有可能一切都是完善的，但仍旧会出错。注释并不是洁净代码的替代方法，而是代码的固有组成部分。 代码注释解析 在进一步争辩我们的问题之前，先让我们来看看不同的代码注释风格。 /** * Javadoc-style documentation comment. */ void foo(void) { if (bar 10) { /* regular comment */ ... } } 常规注释就是编程言语本身定义的注释。依据阅历，它们不应当被广泛使用，由于它们倾向于用来解释代码在做什么。 另一方面，文档注释从外部角度描述了全局变量、函数和模块。在函数体内部，它们基本上就是常规注释，工具通常会忽视它们。假如在函数内部有一些值得描述的东西，看看能否可以把它们放进函数描述本身。 文档注释本质上就是常规注释加上一些额外的附件，例如额外的正斜杠?///?doc?comment、感叹号?//!?doc?comment?或者?/*!?multiline?doc?comment?/，或者 Javadoc 注释中的附加星号 /* doc comment */。实际上，其他编程言语和工具也支持 Javadoc，所以这里就以它为例子。 当然，你也可以使用常规注释，并忘掉那些时髦的标签。不过，一些文档生成器（如 Doxygen 或 Sphinx）可以直接依据注释创建 PDF、HTML 或手册页，大多数现代 IDE 为它们供应了额外的显示支持，省得你老是进行上下文切换，而且还可以为你供应一些有用的信息。 除了注释的后处理之外，注释的格式并不重要，重要的是你想要表达什么。 冗余的注释聚焦在错误的信息上 我们已经得出结论，即不应当记录代码在做什么，而是记录为什么要这么做以及怎样做，但这到底意味着什么呢？ 人们不宠爱写注释的一个常见缘由是“它们只是在陈述已经很明显的东西”，所以注释是多余的。对于一般性的注释，的确难以反对，特殊是在面对对象言语的封装方面。一些简约的函数，比如 get_temperature() 的一般性描述可能如下所示： /** * Returns the temperature. */ int get_temperature(void) { return temperature; } 这里的注释的确没有添加太多的价值，它本质上只是反复了函数的名字，只是在说明这个函数的作用。这不是我们想要的，我们想要的是代码没有告知我们的东西。 这个函数格外简约，所以写注释是确定没有必要的。但话又说回来，