摘要:Robert Kozak, 来自Delphi R&D, 讨论关于正确的代码编写方法.
// 我有一个注释
by Robert Kozak (Delphi R&D)
两个月以前，我有机会去回顾一下我第一次为Delphi工作的时候所编写的一些代码。我实在是不愿意承认那是我写的－因为他们实在是太糟糕了。这当然是一段令人羞辱的经验。我的技术自从那个时候以来已经有了长足的进步。事实上，我注意到了在这几个月里我的改变。不知道你是否曾经回过头去看看半年前你写的代码。我敢打赌你脑海中一定是“我在想什么呢？我肯定不会这样写的。”
如果你曾经不得不维护你上一个项目的代码，我敢打赌那一定是很痛苦的。更令人痛苦的是你不得不去维护其他人的代码。唯一一种可以使这种痛苦减轻的方法就是一个好的注释。注意我说的是“好的”注释。不好的注释实际上还不如没有注释呢。举例来说，我们看看下面这段代码，它都做了些什么？
上面的这段注释绝对没有任何意义，它不能告诉你这段代码的功能。还有更好的吗？
写出好的注释的诀窍就是问问你自己为什么要写这段注释。在你的注释里，不要试图去写代码是怎么工作的，而是要解释你为什么要写它。特别是，你写的注释如果走对了路的话，它们会很精简。
(* 注释的种类 *)
注释分五个基本的类型。我会按照由差到好的顺序解释他们
重复代码
这种类型的注释只是用另外一种方式重新描述了一便代码，而没有任何其他的附加信息。这种注释要绝对避免。
解释代码
这种类型的代码常常是解释一段复杂的或是技巧性的代码。这种类型的注释比较容易理解，它们对于重写这段代码一般是比较有帮助的。
标记
标记一般是为你自己或者是你小组里的其他成员所做的一段临时的信息。现在Delphi 5的编译器可以识别//TODO注释。最初，我使用 //rk: 而我的一个朋友使用//\\来标记代码，这些标记在项目完成以后都是应当去掉。
代码的总结
这种类型的注释以简短的语言总结了代码。这比仅仅简单的重复代码要好的多，因为它可以让一些不熟悉你的代码的人快速的浏览你的代码。
描述代码的目的
这种是解释代码的意图，换句话来说，是代码为什么这样写。这种类型的注释很容易阅读，并且给你提供了理解代码的必要信息。
{注释的方法}
好，现在我们知道应该使用后两种类型的注释(代码的总结和描述代码目的)。让我们来看一些可以适当的使用它们的技术。这里有5个基本的区域可以使用注释：
只有一行的代码，代码段，数据结构，函数，单元和工程
只有一行的代码(Individual lines)
如果你希望写出好的注释(这正是我们的目的所在，不是吗？)，那么你在只有一行的代码中只能使用两种注释。第一种，这行代码很复杂，需要进行解释。尽管重新编写一段复杂的函数来澄清它的意图是比较容易的，但是对于一行代码来说却很难。第二种，这行代码有错误，你想记录下来以便以后修改。
我一般会在在一行代码后面紧接一段注释。就象下面这样：
这种方法一般会因为没有的足够空间来澄清代码的意图而演变为重复代码。它也因为很难保持代码的排列和对齐而趋向于使用缩写词。唯一一种合适的用途是用来解释数据声明、维护注释或者是一段代码的结束标记(例如 //end if, //end while 等)。数据声明会因为这种注释而尽量短，因为这样可以留出更多的空间来注释。如果你在每一个数据声明的上面都加上这种注释的话，会难以保持数据声明的连贯性。维护注释一般要尽量的短，主要是记录初始化信息、数据和错误数目。它一般并不是真正的注释代码的意图，所以用这种方式(代码后紧跟注释)是比较合适的。
代码段
这是最常用的(也是最好的)一种方法来注释你的代码。用这种方式注释要描述清楚代码的意图。不要忘记，要集中描述“为什么”而不是“怎么做”。这种类型的注释要为读它的人说明接下来要做什么，他们可以通过注释搞清楚代码在做什么。
数据结构声明
这里的注释用来描述变量声明以及描述变量的名字所不能表达出来的东西。例如他们的单位(公里，英尺，磅等)。变量注释应当出现在变量声明的地方，如果你有一些标记型变量(flag bariables)，它们每一位都有不同的含义，那么它们都需要注释。
函数
有些人会告诉你，每一个函数都需要一个巨大的统一风格的注释。这真是可笑。最简单的一点，这样会使注释很难以阅读，并且距离它所描述的代码也很远。好的注释应当在它所描述的代码的附近，而且一般来说，几行的注释就足够了。如果要经常考虑到函数的细节问题，我们就需要更多一点的详细信息，看下面这个例子：
我经常会在这段代码上遇到麻烦，因为我总是忘记哪一个是 Sender 哪一个是Target。即使在我自己的代码里面，在带有这种 Sender 和 Target的函数里，我仍然会忘记哪一个是导入的变量，哪一个是导出的变量。一个注释可以在很大程度上减轻这种混乱。还有其他一些可以放在函数注释里面的是(如果需要的话)：接口设想，修改历史记录，函数的限制，全局的影响，算法的来源以及使用的设计模式。
单元和工程
最后，我们讨论到单元和工程。当给一个单元和工程文件注释的时候，你可以用简短的语言描述每一个文件的目的。你也可以包含修改历史记录、主要对象的描述和使用的设计模式。你也可以包含你的名字和联系方式(电话号码或email)，这样如果有人维护你的代码的时候，他们可以和你联系。另外，如果有版权信息的话，也可以加进去。
//end file
如果你喜欢我的话，你就应当好好提高你写注释的技巧。编写注释不应是一件困难和费时费力的事情。只要记住，你的代码说明“怎么做”，而你的注释说明“为什么”。如果你能一直记住这一点的话，我想就连我也能看懂你的程序。
{ TODO: 更多的信息请看 Code Complete by Steve McConnell, Microsoft Press }
