最近看到一篇短文《Writing Great Git Commit Messages》介绍如何写Git代码的签入注释。文章不长,但却抓住了软件工程中一个最常见的问题 - 应该写什么样的注释? 我们都有这样的体会,接手别人的代码是一件最头疼的事情,往往不是因为别人的代码质量差,而是因为你根本就无从判断其质量,有太多的 why?????? 无法从读代码中找到答案,也就根本无从判断他的代码质量高低。
当你抱怨别人的代码注释或者签入注释都是一堆无用的“垃圾”时,此时你是最清楚什么样的注释你想要的,你需要能够回答 why? why? why? 的注释, 就像上文中所指出的:
“Anyone can see WHAT you did just by looking at the code. But the code can never tell someone WHY you did it.”
注释不是为了解释你做了什么,而是要说明你为什么(why)要做这个。因为你做了什么(what)和怎么做(how)是可以慢慢从代码中读出来的,而为什么做只能靠注释保留了。