程序文档与doxygen

    很多的程序员都不太喜欢写文档，至少我不太喜欢。但是如果让你维护别人的程序，一点文档都没有，那是件极其痛苦的事情。这种事情我最近就碰到了，我的一个同事离职了，然后上头就把他之前写的程序扔给我。那程序是用Python写的，本来Python是一门让程序变得更加简单易懂的语言，而我那同事居然能把Python用得那么晦涩难懂。它所有的程序都没定义一个class，当需要保存多个属性的信息时，他把这些信息都放在一个list里面，然后用listvar[1], listvar[2],...,listvar[n]来引用这些属性，弄得整屏都是[]。当你看到一个地方的时候，你经常要翻到前面去看这个listvar的每一项的意思，这实在太折磨人了。更加痛苦的是他的程序没有文档（代码注释都很少），整个下来就像是在解码。

    如果你的程序只有你自己看，而且对程序逻辑长时间都能非常清晰，那不写文档还可以。不然的话没文档就是意味着浪费自己或别人的时间！一般情况下，程序文档是不需要太多的，好的代码本身就是文档，这跟编程风格有很大关糸。关于编程风格，Google C++ Style Guide 可以作为一个参考。我那同事就是没有好好利用代码本身的文档功能。此外，对于程序文档，很大一部分不用自己写，因为有很多自动生成文档的软件，其中doxygen就是一个使用非常广泛的文档生成工具。

 

    这周刚好我也要把一个自己之前写的软件交给别人维护，需要整理一些开发文档出来。doxygen我很早就听说过，那时候只是瞎搞了一下，没有具体应用到实际当中。现在想起来这么个工具，就赶紧下载安装，在linux下源码安装也相当简单。接着就学如何使用doxygen。doxygen的使用文档很多，我在它的官网上面只看了manual页面的两个section(Getting started & Document the code)就基本上够了。然后按照manual里说的生成并修改配置文件，在代码里采用指定的注释风格，最后就可以自动生成文档了。生成的文档不仅内容丰富，而且还挺好看。
    我还了解了一下doxygen的作者，它其实是一个人写，而且这个人一做就是十几年（从1997年开始）。另外doxygen是以GPL发布的，作者应该不会因此得到什么经济收入。作者的执着和分享很值得我们学习。

    doxygen官网是：http://www.stack.nl/~dimitri/doxygen/ 。