优雅编程---注释

C1:不恰当的信息
让注释传达本该更好地在源代码控制系统、问题追踪系统或任何其他记录系统中保存的
信息，是不恰当的。例如，修改历史记录只会用大量过时而无趣的文本搞乱源代码文件。通
常，作者、最后修改时间、SPR数等元数据不该在注释中出现。注释只应该描述有关代码和
设计的技术性信息。
C2:废弃的注释
过时、无关或不正确的注释就是废弃的注释。注释会很快过时。最好别编写将被废弃的
注释。如果发现废弃的注释，最好尽快更新或删除掉。废弃的注释会远离它们曾经描述的代
码，变成代码中无关和误导的浮岛。
C3:冗余注释
如果注释描述的是某种充分自我描述了的东西，那么注释就是多余的。例如:

i++; 1/ increment i
另一个例子是除函数签名之外什么也没多说(或少说)的Javadoc:
/**
* @param sellRequest
@return
@throws ManagedComponentException
public sellResponse beginSellItem(SellRequest sellRequest)
throws ManagedComponentException
注释应该谈及代码自身没提到的东西。

C4:糟糕的注释
值得编写的注释，也值得好好写。如果要编写一条注释，就花时间保证写出最好的注释。
字斟句酌。使用正确的语法和拼写。别闲扯，别画蛇添足，保持简洁。
C5:注释掉的代码
看到被注释掉的代码会令我抓狂。谁知道它有多旧?谁知道它有没有意义?没人会删除
它，因为大家都假设别人需要它或是有进一步计划。
那样的代码就这样腐烂掉，随着时间推移，越来越与系统没关系。它调用不复存在的函
数。它使用已改名的变量。它遵循已被废弃的约定。它污染了所属的模块，分散了想要读它
的人的注意力。注释掉的代码纯属厌物。
看到注释掉的代码，就删除它!别担心，源代码控制系统还会记得它。如果有人真的需
要，可以签出较前的版本。别被它搞到死去活来。