概述

在Qt Creator中进行C++开发时，统一的代码注释规范能够显著提升代码可读性和团队协作效率。手动编写重复的注释内容既耗时又容易出错，Qt Creator提供的片段(Snippets)功能可以完美解决这一问题。

配置代码片段

依次打开Qt Creator菜单栏的【工具】→【选项】→【文本编辑器】→【片段】。

点击【添加】按钮创建新的代码片段。设置触发关键词（如filecomment），这样在编辑器中输入该关键词后按Tab键即可自动展开注释模板。

文件头注释模板示例：

/*!
 * @file      : %{CurrentDocument:FileName}
 * @brief     : 文件功能简要描述
 * @details   : 文件功能详细说明
 * @author    : Developer
 * @date      : %{CurrentDate:yyyy-MM-dd} %{CurrentTime:hh:mm:ss}
 * @version   : 1.0.0
 * @copyright : Copyright © 2024
 *
 **********************************************************
 *
 * @note 修改记录:
 * <table>
 * <tr><th>日期</th><th>版本</th><th>作者</th><th>描述</th></tr>
 * <tr><td>%{CurrentDate:yyyy-MM-dd}</td><td>1.0.0</td><td>Developer</td><td>初始版本</td></tr>
 * </table>
 *
 **********************************************************
 */

类注释模板示例：

/*!
 * @class     : ClassName
 * @brief     : 类功能描述
 * @author    : Developer
 * @date      : %{CurrentDate:yyyy-MM-dd} %{CurrentTime:hh:mm:ss}
 */

函数注释模板示例：

/*!
 * @fn        : FunctionName
 * @brief     : 函数功能描述
 * @param     : 参数说明
 * @return    : 返回值说明
 * @author    : Developer
 * @date      : %{CurrentDate:yyyy-MM-dd} %{CurrentTime:hh:mm:ss}
 * @note      : 注意事项
 */

完成编辑后点击右下角的【Apply】按钮保存配置。

设置新建文件模板

Qt Creator支持在新文件创建时自动添加文件头注释。首先将注释模板保存为文本文件（如header_template.txt），确保文件编码为UTF-8。

然后依次打开【工具】→【选项】→【C++】→【文件命名】。

在页面底部的license template区域点击【浏览】按钮，选择先前保存的模板文件。配置完成后，创建新的C++源文件或头文件时将会自动添加预设的注释头。

使用技巧

• 片段触发关键词应简短且易记，建议使用驼峰命名或下划线命名
• 利用Qt Creator内置的变量（如%{CurrentDate:yyyy-MM-dd}）实现动态内容
• 可为不同语言（C++、QML等）分别设置对应的注释模板