晨光（Morning） 注释 注释是源码的终生伴侣，这一点是毋庸置疑的。她通常用来解释源码的控制流程，或者是类、函数、变量的说明等等，用以体现程序书写者的意图、目的。关于注释的问题，归纳起来不外乎“何时写？”，“写什么？”，“怎么写？”。对于某些程序员而言，写注释似乎是一件很费脑筋的事情。试想，在酣畅淋漓的coding时，如何愿意打断思路去考虑注释的书写；而完成coding后，又如何愿意回过头去考虑添加注释呢？这种状况很容易养成习惯。本文准备就此提供一些一般性的建议，但并不涉及具体的注释格式和方法。这些内容可以在相关的书籍和文章中找到。[1] 注释首先应该不至于侮辱每个程序员的智力，一些显而易见的解释似乎是可以省略的，也不要简单重复源码已经表达的信息，因为这是多余的。不应该把添加注释看作是一种形式上的任务或责任，并且，这也不是简单的被动行为。 注释应该易于阅读和理解，这不光是有利于自己，还包括他人，你的后继者可能会接手你的代码。正所谓利己利人，损人害己的事情是最可怕的。好的注释其实是需要文字功底的，它应该做到清晰、简洁、精准、有价值。 注释的出现频率应该是适当的，她只在需要的地方才会出现，并且某处的内容也不易过分的多。过多的注释会把代码分割得支离破碎，以影响流畅性，从而影响阅读者思路的连贯性。大段的注释或许经常会被那些急性子的阅读者忽略掉，他到宁愿去啃那些硬梆梆的，却是实实在在的代码。 代码随着时间的推移很有可能会慢慢改变其本来面目，一个粗心的、或是懒惰的程序员，极有可能忘记及时保持代码和注释的一致性。这样的错误或许优秀的程序员也可能会犯，人非圣贤，熟能无过。其实，保持这种一致性，本身就是编写代码以外的额外开销，它是必要的，却也需要付出成本。如果在开始写注释的时候就尽量考虑减少以后维护的代价，那么这种同步的维持会相对轻松些。可以在维护上少花些精力，此等好事，相信任何人都会赞成的，包括你和你的老板。一个显而易见的例子是：避免在注释里引用易变的代码信息，这是造成代码和注释不同步的一个重要诱因。 切记，注释并没有强制约束力，这一点和文档相似。如果你没有遵守注释中所写明的某个函数的使用注意事项，程序仍可以顺畅地执行，直至遇到致命错误，或许你要为此付出痛苦调试的代价。所以，如果希望强制约束的话，就该尽可能利用程序设计语言自身的功能和特点，争取让编译器在生成可执行代码之前，自动帮你找到问题所在，或者是利用断言（assert）来澄清事实。 规范化的注释还可以有助于自动生成部分开发文档，或许这可以免去你书写开发文档的一部分精力。Java Doc就是一个明显的例子。 此外，注释还可以起一些额外的作用。比如，在写程序时，对于目前还未实现的代码，注释可以作为一种助记符或备忘录，以备经后在此处添加代码。它可以描述一个程序的局部流程，表达程序员的某些意图和思路。至于这些注释最终是否被保留，则视情形而定。用这种方式的一个好处是，尽管代码未曾实现，但是意识了然，并且这种行为没有破坏现有程序，它仍然可以被编译通过。另一个把注释作为助记的例子是，当你对某段代码的合理性表示怀疑而是时又想不到更有效的解决办法时，可以在旁边加上诸如“FIXME”这样的词并配以简短的说明。当你有足够精力来考虑这些曾被你怀疑为潜在问题的时候，一个简单的文字查找功能，就可以将这些危险的家伙全部揪出来（目前的文字编辑工具一般都会有Find甚至是Find In Files功能，应该善于运用这些强大的功能）。 最后，对于那些过分热衷于注释的朋友，我想提醒一点：最后真正交付运行的唯有代码。如果代码完全可以说明一切，那么注释就是添足之笔；如果在考虑如何写注释时，代码本身却存在问题，请先关注一下你的代码和设计。 [1] 这里给出部分与注释相关的参考资料： 陈世忠，《c++编码规范》，人民邮电出版社，2002.6 Java语言编码规范，英文（http://java.sun.com/docs/codeconv/html/CodeConvTOC.doc.html） Java语言编码规范，中文（http://morningspace.51.net/resource/javacodeconv.html）