c语言注释产生代码,C语言编程规范——注释篇

一、关于Doxygen

Doxygen是一种开源跨平台，以类似JavaDoc风格描述的文档系统，完全支持C、C++、Java等语言，部分支持PHP、C#。

利用Doxygen可以将程序中的特定注释转换成为说明文件。同时，利用Doxygen也可以提取代码结构，自动生成包含依赖图、继承图以及协作图来可视化文档的关系，使得代码的可读性更强。

二、关于注释的说明

注释的主要原则是有助于对程序的阅读理解，但注释不宜太多或太少，在需要注释的地方一定要加上，但在能够通过命名等能够体现编程意图的地方则不需要，力求注释准确、易懂、简洁，主要做到以下几点：

·避免对单独语句进行注释；

·通过注释解释为什么这么做、或者要做什么，使代码的读者可以只阅读注释理解代码；

·对读者可能会有疑问的地方进行注释；

·对数据定义进行注释，而不是对其使用过程进行注释；

·对于难于理解的代码，进行改写，而不要试图通过注释加以说明；

·对关键的控制结构进行注释；

·对数据和函数的边界、使用前提等进行注释；

·由于中文支持问题，注释尽可能都采用英文描述。

三、基于Doxygen格式的C语言注释

要想利用Doxygen生成对应的注释文档，那么就需要按照Doxygen的格式来注释代码。

首先对于一个项目而言，可能分成了很多个模块，那么就需要使用@defgroup来定义一个模块。

定义模块

当需要将某个文件加入到特定的模块，使用addtogroup

添加到模块

模块定义执行完成之后，需要对文件进行相关的说明，在Doxygen下，使用\file或@file这样的方式来标注，参考如下：

文件头示例

对于不需要生成说明文档的注释按照以下格式即可：

注释格式

对于对外提供的函数，需要使用doxygen生成注释的，需要按照以下格式对函数参数，返回值，用途等进行说明。

函数格式

而对于不需要对外提供，仅仅在当前文件中使用的函数，需要使用static关键字，可进行简单注释即可。

static void an_example_function(void)

{

}

对于结构体，共用体，枚举类型而言，按照以下格式注释：

结构体注释

若按照以上格式进行注释，即可让编写的C代码更易读，同时也可以利用现有工具生成完整的说明文档。