|
// 我有一个注释
by Robert Kozak (Delphi R&D)
两个月以前，我有机会去回顾一下我第一次为Delphi工作的时候所编写的一些代码。我实在是不愿意承认那是我写的－因为他们实在是太糟糕了。这当然是一段令人羞辱的经验。我的技术自从那个时候以来已经有了长足的进步。事实上，我注意到了在这几个月里我的改变。不知道你是否曾经回过头去看看半年前你写的代码。我敢打赌你脑海中一定是“我在想什么呢？我肯定不会这样写的。”
如果你曾经不得不维护你上一个项目的代码，我敢打赌那一定是很痛苦的。更令人痛苦的是你不得不去维护其他人的代码。唯一一种可以使这种痛苦减轻的方法就是一个好的注释。注意我说的是“好的”注释。不好的注释实际上还不如没有注释呢。举例来说，我们看看下面这段代码，它都做了些什么？
上面的这段注释绝对没有任何意义，它不能告诉你这段代码的功能。还有更好的吗？
写出好的注释的诀窍就是问问你自己为什么要写这段注释。在你的注释里，不要试图去写代码是怎么工作的，而是要解释你为什么要写它。特别是，你写的注释如果走对了路的话，它们会很精简。
(* 注释的种类 *)
注释分五个基本的类型。我会按照由差到好的顺序解释他们
重复代码
这种类型的注释只是用另外一种方式重新描述了一便代码，而没有任何其他的附加信息。这种注释要绝对避免。
解释代码
这种类型的代码常常是解释一段复杂的或是技巧性的代码。这种类型的注释比较容易理解，它们对于重写这段代码一般是比较有帮助的。
标记
标记一般是为你自己或者是你小组里的其他成员所做的一段临时的信息。现在Delphi 5的编译器可以识别//TODO 注释。最初，我使用 //rk: 而我的一个朋友使用 //\\ 来标记代码，这些标记在项目完成以后都是应当去掉。
代码的总结
这种类型的注释以简短的语言总结了代码。这比仅仅简单的重复代码要好的多，因为它可以让一些不熟悉你的代码的人快速的浏览你的代码。
描述代码的目的
这种是解释代码的意图，换句话来说，是代码为什么这样写。这种类型的注释很容易阅读，并且给你提供了理解代码的必要信息。
{注释的方法}
好，现在我们知道应该使用后两种类型的注释(代码的总结和描述代码目的)。让我们来看一些可以适当的使用它们的技术。这里有5个基本的区域可以使用注释：
只有一行的代码，代码段，数据结构，函数，单元和工程
只有一行的代码 (Individual lines)
如果你希望写出好的注释(这正是我们的目的所在，不是吗？)，那么你在只有一行的代码中只能使用两种注释。第一种，这行代码很复杂，需要进行解释。尽管重新编写一段复杂的函数来澄清它的意图是比较容易的，但是对于一行代码来说却很难。第二种，这行代码有错误，你想记录下来以便以后修改。
我一般会在在一行代码后面紧接一段注释。就象下面这样：
| 
本类阅读TOP10
