写注释

在写代码时，即便你认为你的代码不会被别人读到，也应该写好注释。因为当你对一个问题非常熟悉时，你会非常明白这些代码的作用，但当过了几个星期后再来读这段代码时，则需要绞尽脑汁的回想这些代码在干什么。

你不必对那些浅显易懂的代码写过多的注释，比如每个变量、每一行都写注释。但你应该对所有的函数、它们的参数和返回值进行注释，除此之外，对于那些值得注意的或是比较怪异的算法和技术也应当写好注释。对于其他阅读你代码的人来说，注释就是一种提示，只要阅读注释、函数名和参数，就算不读其它部分的代码也能大概理解程序的逻辑。比如，这里有五六行代码完成了某个功能，如果有一行描述这段代码功能的注释，读程序的人就不必再去关注代码的实现细节了。代码注释的写法并没有硬性规定，但有些代码片段（比如正则表达式）需要比代码本身更多的注释。

过时的注释会造成误导，这比不写注释还要糟糕。保持注释的状态为最新的习惯非常重要，尽管对很多人来说这很难做到。

在下一小节我们会讲到，利用注释可以自动生成文档。