我为什么建议你这样写注释

1. 摘要

本文档主要用来指导和建议工程师如何写好软件代码的注释，方便使用Doxygen生成文档

2. 准备工作

安装Doxygen软件

正常的代码工程

3. 实施

好的注释习惯，往往会为你节省很多时间，不管是给自己以后阅读代码还是给别人都是一种良好的开发习惯，而按照一定的规则注释，还可以利用工具直接生成文档，方便代码审阅或者联合开发。Doxygen就是开发中广发使用的工具，如果你留意的话，很多的源码包都是使用Doxygen来生成代码文档，如下图就是我使用Doxygen为工程生成的文档中的一个文件展示

而生成这样的文档，注释就要按照Doxygen的规则，注释就要按照类似如下的格式来书写

更多的书写规则可以参考Doxygen的手册文档，https://www.doxygen.nl/manual/index.html

每一章都讲解的很详细，从安装到开始使用，可以说是step by step。

如果你记不住没关系，，可以多翻阅，这些规则都有例子，或者参阅一些源码包的注释，如我们来看一些源码包中的注释风格：

如lwip 协议栈源码包中的就是按照doxygen来注释的，只要运行相应文件就可以生成文档。

可以看到注释风格就是Doxygen 要求的。同样在其他一些常用的源码包里，大部分都是使用了doxygen来生成相应的文档。这样整个项目的结构和接口都会生成一个详细的文档，可以支持不同格式。大大方便了工作汇报，代码审阅评审，以及联合开发的接口沟通。所以大大推荐采用Doxygen的格式来写注释。尤其现在对中文的支持也越来越好了。