使用 Doxygen 生成文档注释

全文是个人关于注释的观点，很可能有误，不想误人子弟，请慎重考虑其中的任何一个观点 ，欢迎拍砖。

注释不是越多越好

刚开始学编程的时候，总是会有一些老鸟程序员告诉我，优秀的程序员都习惯给自己的代码 加上大量的注释，这一点甚至有很多的老师都是这么教的，以至于有很长一段时间我都对这 个观点深信不疑。

第一个让我这个观点产生怀疑的人是“林纳斯·托瓦兹”，有一段时间疯狂的迷恋操作系统的 内核，而我尝试读一些源码的时候发现，大神们写的代码其实并不会有太多的注释，但是他 们的代码依旧很漂亮。

第二个让我对于注释越多越好的观点产生怀疑的人是C++之父，忘记在他的那一本书中看到 ，注释如果和源码不同步比没有注释更糟糕。

注释是你的源码的一部分，只要你选择写下一行注释，你就需要担负起维护它的责任。我们 经常会在重构一段源码的时候忘记给更改的地方的注释加上相应的修改。最后留给源码的阅 读者无尽的苦恼这段代码怎么就能实现注释里面说的这个功能呢。

代码的可读性远远比注释更重要

所有的程序员都应该像白居易学习，把你的代码写得简单明了，逻辑清晰。写一段清晰易懂 的代码，远比写一段晦涩难懂的代码加上一段晦涩难懂的注释要好的多。所以在你打算写下 一段注释之前先看看你的代码，命名是否规范啊？逻辑是否清晰呢？嵌套层次是否合理呢？ 函数是否够精简呢？

如果以上的问题你的答案都是“是”，而你依然觉得代码相对难懂，那就加上一些简洁的注释 吧，同时记得在更新代码的时候，更新你的注释。

接口的注释

本文提到的接口指的函数签名，包括普通函数、成员函数等

以上这些论述只是针对了源码的注释，个人认为接口的注释还是需要尽可能详细的，因为接 口本身通常都是比较稳定的，此外接口本身能够提供的信息也相对较少，而接口作为模块之 间交互的协议规范，不应该有任何模棱两可的东西，需要详细、准确。

接口的文档中应该包括哪些内容

个人认为以下信息是需要出现接口的文档中的：

• 接口的功能。
• 接口的前置条件，通常是指输入的参数需要遵循的条件。
• 接口的后置条件，通常是指接口的返回值，或者说接口的side effect。
• 接口的注意事项，如果有的话，应该说清楚调用该接口需要特别注意的地方。比如会抛些 什么异常。

使用 Doxygen 生成 C++ 代码文档

Doxygen可以用来从C++的源码注释中抽取文档，目前可以说是C/C+