Doxygen注释规范（C/C++）、以及中特殊注释的妙用--TODO、FIXME、XXX、HACK、BUG、NOTE、WIP

一、妙用代码中特殊注释——TODO、FIXME、XXX、HACK、BUG、NOTE

注释格式	说明
# NOTE:	用于标记需要注意的地方，如重要信息、提示等
# TODO:	用于标记待办事项，提醒开发者需要完成的任务
# FIXME:	用于标记需要修复的问题，通常是在代码中已知的错误或需要改进的地方
# XXX:	用于标记代码中需要优化的地方，可能是一些潜在的问题或需要注意的细节
# HACK:	用于标记一些临时的、不太优雅的解决方案，通常是为了快速解决问题而采取的权宜之计
# BUG:	用于标记已知的bug，提醒开发者需要修复

1.1 最常用的三种特殊注释：

TODO表示待完成的功能，FIXME表明代码需要修正或存在错误，XXX则用于标记待优化的实现。这三种注释为团队协作和代码维护提供了清晰的指南

TODO - 待办事项。

TODO表示这里有待完成的任务或者待实现的功能。
如果代码中有该标识，说明在标识处有功能代码待编写，待实现的功能在说明中会简略说明。

No problem, but addtional code needs to be written (usually when you are skipping something)情未了

FIXME - 待修理或存在问题。
指出代码中存在问题或bug，需要修复的地方。
如果代码中有该标识，说明标识处代码需要修正，甚至代码是错误的，不能工作，需要修复，如何修正会在说明中简略说明。
This works, sort of, but it could be done better. (usually code written in a hurry that needs rewriting) Fuck Me

XXX - 待优化的实现
表示代码可能包含临时解决方案、糟糕的实践、或者有待优化的部分，通常意味着此处的实现方式并不理想，应在未来重新审视和改进。
如果代码中有该标识，说明标识处代码虽然实现了功能，但是实现的方法有待商榷，希望将来能改进，要改进的地方会在说明中简略说明。
Warning about possible pitfalls, can be used as NOTE:XXX:陷阱

 总结起来，代码注释中的 TODO、FIXME、XXX 是三种不同层次、不同紧迫程度的代码标记。

• TODO 提示未来添加或完善的功能，
• FIXME 指出需要尽快解决的问题，
• XXX 警告其他开发人员注意代码中的潜在风险或复杂性。

这些标记的正确使用，有助于开发团队更高效地协作和管理代码。

1.2 其他注释：

HACK 或 HACKER - 临时方案
标记一段临时性的、非常规的解决方案，通常用于应对紧急问题，但长期来看不是最优解。
英语翻译为砍。如果代码中有该标识，说明标识处代码我们需要根据自己的需求去调整程序代码。
Not very well written or malformed code to circumvent a problem/bug. Should be used as HACK:FIXME:补锅踩雷填坑

OPTIMIZE 或 PERFORMANCE - 性能攸关
标记可能影响性能的地方，需要进一步优化。

BUG - 故障
There is a problem here.丢锅埋雷挖坑

NOTE 或 NOTICE - 提示
提供一些重要提示或背景信息。
escription of how the code works (when it isn’t self evident) 汝等凡人

REVIEW - 待评审
请求他人复查某段代码，可能是为了确认设计决策、逻辑是否正确或改进代码质量。

DEPRECATED - 废弃
标记已弃用的代码，提醒开发者这段代码未来可能会被移除。

UNDONE 或 WIP (Work In Progress) - 进行中未完成

标记正在进行的工作，表明这部分代码尚未完成。

 二、Doxygen注释规范（C/C++）

链接：Doxygen中文手册

2.1 块注释

片段注释（代码前注释，解释后面一/多段）

/**
 *
 *  ……  适合一个片段
 *
 */

/************************************************
 * ……   适合分割多个片段                           *
 ************************************************/

行注释（代码前注释，解释后面一行）

///…
/** …… *

批注（代码后注释，解释前面一行）

/*!< ... 批注 ... */
/**< ... 批注 ... */ （推荐）
//!< ... 批注 ...
///< ... 批注 ...    （推荐）

2.2 文件注释

/**
 * @file 文件名
 * @brief 简介
 * @details 细节
 * @mainpage 工程概览
 * @author 作者
 * @email 邮箱
 * @version 版本号
 * @date 年-月-日
 * @license 版权
 * @copyright Apple Inc.
 */

e.g.

/**
 * @file Test.h
 * @brief 测试头文件
 * @details 这个是测试Doxygen
 * @mainpage 工程概览
 * @author SunTroop
 * @email suntroop@sina.com
 * @version 1.0.0
 * @date 2017-11-17
 */

2.3 函数注释

简约版

/**
 * @brief 函数简介
 *
 * @param[in]     形参 - 参数说明
 * @param[out]    形参 - 参数说明
 * @param[in,out] 形参 - 参数说明
 * @return 返回说明
 *     @retval    返回值 - 说明
 */

 详细版

/**
 * @brief  函数简介
 * @detail 详细说明
 * 
 * @param  形参 参数说明
 * @param  形参 参数说明
 * @return 返回说明
 *   @retval 返回值说明
 * @note      注解
 * @attention 注意
 * @warning   警告
 * @exception 异常
  */

 

 e.g.

/**
 * @brief 主函数
 * @details 程序唯一入口
 *
 * @param[in] argc - 命令参数个数
 * @param[in] argv - 命令参数指针数组
 * @return 程序执行成功与否
 *     @retval 0 - 程序执行成功
 *     @retval 1 - 程序执行失败
 * @note 这里只是一个简单的例子
 */
int main(int argc, char* argv[])

 

 

下面一些标注方式可以根据需要选择使用。

Doxygen 命令关键字

命令	生成字段名	说明
@see	参考
@class	引用类	用于文档生成连接
@var	引用变量	用于文档生成连接
@enum	引用枚举	用于文档生成连接
@code	代码块开始	与@endcode成对使用
@endcode	代码块结束	与@code成对使用
@bug	缺陷	链接到所有缺陷汇总的缺陷列表
@todo	TODO	链接到所有TODO 汇总的TODO 列表
@example	使用例子说明
@remarks	备注说明
@pre	函数前置条件
@deprecated	函数过时说明

 

2.4 类型/宏定义/枚举/结构·注释

/**
* 2字节字符类型                                                                 
*/
typedef unsigned short WORD;

/// 缓存大小
#define BUFSIZ 1024*4 ///< 缓存大小

/**  枚举类型*/  
enum COLOR{
    RED=0,   ///<  红色 
    GREEN=1, ///<  绿色 
    YELLOW=2 ///<  黄色 
};

/// 针清洗（灌注）参数
typedef __packed struct
{
    U8 id;            ///< 1：样本针 2：试剂针
    U32 errCode;    ///< 次数
}NEEDLE_CLEAN_BACK;

 

2.5 常量/变量·注释

代码前注释·格式

/// 注释
常量/变量

e.g.

/// 缓存大小
#define BUFSIZ 1024*4

 代码后注释·格式

常量/变量 ///< 注释

e.g.

 #define BUFSIZ 1024*4 ///< 缓存大小