最近在阅读WordPress-3.0.4的源代码。总的感觉是代码结构清晰，简单明了。当然，最深的感触还是WordPress代码中的文档和注释–非常详细。WordPress的代码中详细记录了每一个模块的功能，变更历史；每一个class的功能，作用范围；每一个函数的功能，接口参数，以有返回值…从WordPress源代码的读者方面来说，有了如此丰富的文档和注释，阅读WordPress的代码是一件相对容易和有趣的事情。

从WordPress项目本身来说，对于一个新加入的开发者来说，有如此详细的文档和注释，即使在没有其它的成员的帮助的指导的前提下，新加入的成员也能很容易地从中了解WordPress的整体架构和逻辑流程。这一点，对于WordPress这个优秀的开源项目的发展壮大也是至关重要的。

很多不喜欢写注释和文档的开发者总喜欢说: “代码就是最好的注释，我的代码是自解释的，所以文档不是必需的…”。能做到上述三种自然是好的，但是这并不能代替文档和注释。对于一个大的项目，如果没有文档，一个新手可能需要很长时间才能融入；如果没有注释，对于大部分人来说，自己亲手写的功能模块，在半年之后，可能自己都不让识了，自已都搞不明白其中的逻辑和流程。要知道，文字和图像用于展示信息的能力比代码要强很多倍，所以，有了文档和注释，你能以更快的速度了解一份新的代码。文档和注释，于人于已都是善举。

本站原创文章，转载请注明出处。