也谈代码中注释的问题

        对于代码注释，大家较为一致的看法是代码中一定要有注释，这是毫无疑问的，但是如何去写注释，却是各有各的说法，今天看到一篇博客，其观点是：注释只写why，不写what和how。当然，前提是代码已能够很容易看出 what和how了。看了这博客，我也想谈谈这方面的看法。

        在注释的问题上，很久以前还跟我的一位同事吵过，那位同事在代码上密密麻麻地写满注释，他让我也要这样做，这让我很不能接受，因为我觉得我的代码一下就可以看明白的，不需要那么多的注释，除非他英语很差，需要我把它翻译成中文才能看明白，而且我的注释都是英文的注释，那位同事的注释是全中文的，他几乎为每一行语句都做了中文注释，让我感觉他象是在为他的代码做中文翻译，我始终觉得作为一名程序员，起码要过英语这一关，如果英语不行，可以想象他的代码可读性会非常差，他写的函数名、变量名会很难让人看明白，那只好在他的代码上密密麻麻地写满中文翻译了，但我觉得这样的程序员不是称职的程序员。为函数名、变量名取一个很容易让人看明白的名字，胜过写一大堆的注释，容易让人理解、容易让人记得住的函数名、变量名，用起来也让人舒心，在写代码中最为烦恼的是当要用某个函数或变量时，却不知道名字该怎么打出来，而且总让人记不住，我最恨有这样的函数名和变量名。

        那到底什么样的注释才算是合理的呢？我觉得一方面要让程序员从繁琐的注释中解脱出来，让他能够更加关注程序的设计问题，另一方面还要确保代码的可读性。写代码也关系到做人的问题，有些人仅为自己考虑，觉得只要自己能够看得懂就可以了，殊不知在公司中写的代码是公司的，是很有可能要让其他人接手维护的，所以我们在写代码时也要为别人考虑，要站在别人角度来看自己写的代码，当觉得自己的某段代码或某行语句可能会让人很难理解时，则一定要写上足够的注释，我觉得这是为代码写注释的最基本的原则。

        看别人的代码总觉得很累，代码是抽象的，不管注释再多，要把别人写的代码全部理解下来，总要死掉不少的脑细胞，所以万不得已时我一般不去看别人写的代码，除非那代码需要我去维护，如果想要知道设计方法和思想，我更喜欢去看相关的文档，或直接让写代码的人跟我说说，所以，除了代码之外，我更喜欢的是与代码相关的文档设计，特别是图文并茂的文档，对于涉及复杂算法或流程的程序，如果没有文档，而只有代码，那是件非常让人痛苦的事，复杂的算法或流程是很难用注释可以表达清楚的，对此，我的原则是有文档则先看文档，代码能不看则尽量不看。