大家都知道编程格言“文档化你的代码”（尽管有的人并未遵守），但是今天我还是想谈谈项目中可能存在的三种文档以及它们的重要性。
当和一个PHP程序员讨论注释时，大部分人会立即想到PHP文档块（PHP DocBlocks）。文档块在注释一致性和自动生成文档方面提供了许多便利。文档块天生就特别适用于函数、类等API的文档化，在这方面，它极其出色，无人可及。
然而问题是：为API提供文档——函数参数说明、类的用途以及其它类似说明——仅仅是项目所需的三种文档中的一种而已。而我发现很多PHP程序员，他们认为写完文档块，就已经满足注释和文档的要求了。
事实并非如此。
首先，在一个大型的产品中，需要一个更高层的文档。因为我没有找到这种文档的合适名称，姑且称之为实现文档吧。这个文档不是解释“这有一个你可以使用的类，这些是它的方法”，而是描述在项目中，整个流程是如何处理的，用到了哪些类。
这个文档的范围可以包括项目中的最佳实践到常见编程任务的实现注释。如果仅有大量类的文档，而没有讲述如何把这些类串联起来，完成特定任务的文档，那么对于一个新开发者而言并没有什么帮助。 此外，文档还应该解释清楚session中包含了哪些信息及它们间的关系，它们和数据库数据的关系，以及需要哪些辅助函数去访问这些数据。
现在，我们来看最后一种文档，它也是最容易被那些依赖于文档块的开发者所忽视的：简单有用的行内注释。
用于解释代码行实际功能的行内注释，对于帮助其它程序员阅读并理解你的代码而言是至关重要的。也许你会认为你的那12行代码非常简单，谁的可以理解，但是你要知道，通常情况下，你的同事并不希望只有在了解了函数的各个方面之后，才能修复它导致的bug。能够清楚解释各个代码块功能的好注释对于快速调试非常重要——它允许程序员快速扫描注释，找到对应的代码，而不需要阅读和理解周围的各行代码。
当然，对于行内注释的数量，每个人都有自己的定义，我认为没有一个绝对的标准。我曾经做过一个项目，它要求每一行代码有一行注释。（他们通过软件删除所有实际代码，仅留下注释，方便直接通过阅读注释来了解代码的行为。）
一行代码一行注释可能是小题大做了。但是在满足这个项目需求的过程中，我养成了写大量描述性注释的习惯，所以我觉得这对我是一个很好的学习经历。
根据上面的讨论，下面是我的建议，可以帮助你写出良好清晰的注释：
- 在写代码的时候，先写注释，解释下一步要做的事情，然后再写代码实现（不管是1行还是20行代码）。
- 假设别人仅通过注释，忽略代码，能否在总体上理解每个代码块的功能？如果某些方面不清楚，则添加相应的注释来描述它们。
- 不要害怕写长注释，如果这个代码块很复杂，或者这个问题有一些特殊之处。我宁可阅读5行的注释来了解这个代码为什么要这么做，也不愿意去看一行似乎很丑陋的代码，否则很可能会错误地去修改它，从而破坏了整个应用。
不管怎么样，我希望你能喜欢这个关于注释的简单讨论。无论你是否使用PHP文档块，请尽量保证你的项目包含这三个方面的文档：
- 实现文档，告诉开发者从哪里开始和如何完成任务。
- API文档，描述每个类和函数的细节。
- 行内注释，描述代码本身。
最后，请让我们再重复一遍：“注释你的代码！”
gumoon