CLion 文件头部注释模板配置

在 C/C++ 项目开发中，规范的文件头部注释不仅可以提升代码可读性，还能记录文件的创建信息、版权声明等。本文将介绍如何在 CLion 中配置文件头部注释模板，使其在新建 .h 和 .cpp 文件时自动添加标准化的注释。此外，由于 JetBrains 系列产品（如 IntelliJ IDEA、PyCharm、WebStorm）在 File and Code Templates 的使用方式基本相同，我们也会简单介绍它们的配置方式。

---

1. JetBrains 产品的文件头部注释机制

JetBrains 系列 IDE（CLion、IntelliJ IDEA、PyCharm 等）都支持通过 File and Code Templates 配置文件头部注释，其基本原理相同，但各个 IDE 在具体实现上可能有一些细节区别。

• CLion（主要用于 C/C++）
• IntelliJ IDEA（主要用于 Java/Kotlin）
• PyCharm（主要用于 Python）
• WebStorm（主要用于 JavaScript/TypeScript）

为了保持统一性，我们以 CLion 为重点 讲解，最后会补充 IntelliJ IDEA、PyCharm 等其他 JetBrains 产品的适配方式。

---

2. CLion 的文件模板结构

2.1 进入 CLion 配置界面

1. 打开 CLion。
2. 进入 Settings（Mac 用户为 Preferences）。
3. 导航到 Editor → File and Code Templates。
4. 找到 Includes 选项卡和 Files 选项卡。

2.2 CLion 头文件模板（C++ Header File）

默认的 .h 头文件模板如下：

#parse("C File Header.h")
#[[#ifndef]]# ${INCLUDE_GUARD}
#[[#define]]# ${INCLUDE_GUARD}

#[[#endif]]# //${INCLUDE_GUARD}

优化点
✅ 解析 C File Header.h，确保头部注释自动填充。
✅ 增加 #ifndef 宏定义 (INCLUDE_GUARD)，防止重复包含。
✅ 调整 #endif 注释格式，保证与 #ifndef 变量匹配，提高可读性。
✅ 可以扩展 #pragma once，在 #ifndef 之外提供更简洁的头文件保护方式。

2.2.1 修改 C++ Header File

你可以自定义该模板，例如加入 #pragma once 以替代 #ifndef 宏保护：

#parse("C File Header.h")
#pragma once

2.3 CLion 文件头部模板（C File Header.h）

默认的 .h 头文件模板如下：

#if ($HEADER_COMMENTS)
//
// Created by $USER_NAME on ${DATE}.
#if ($ORGANIZATION_NAME && $ORGANIZATION_NAME != "")
// Copyright (c) $YEAR ${ORGANIZATION_NAME}#if (!$ORGANIZATION_NAME.endsWith(".")).#end All rights reserved.
#end
//
#end

优化点
✅ 保证注释部分的可读性，使用 // 符号让 IDE 更好地解析。
✅ 动态填充 USER_NAME、DATE，避免手动维护。
✅ 自动添加 ORGANIZATION_NAME，并确保其不会带有多余的 .。
✅ 可以结合 Git 进一步扩展，例如自动获取 Git Commit 记录作为 Last Modified 信息。

添加自定义的模板：

#if ($HEADER_COMMENTS)
/**
 * ==================================================
 *  @file ${FILE_NAME}
 *  @brief TODO 描述该文件的功能
 *  @author ${USER_NAME}
 *  @date ${YEAR}-${MONTH}-${DAY} ${TIME}
 *  @version 1.0
#if ($ORGANIZATION_NAME && $ORGANIZATION_NAME != "")
 *  @copyright Copyright (c) $YEAR ${ORGANIZATION_NAME}#if (!$ORGANIZATION_NAME.endsWith(".")).#end All rights reserved.
#else
 *  @copyright Copyright (c) ${YEAR} ${USER_NAME}. All Rights Reserved.
#end
 * ==================================================
 */
#end

优化点
✅ 采用 /** 进行标准化注释，方便 Doxygen 解析。
✅ @file、@brief、@author、@date、@version 等标签让注释结构更清晰。
✅ 自动填充 文件名（$FIL{E}_{N}AME）、作者（${USER_NAME}）、日期时间（${DATE} ${TIME}），避免手动维护。
✅ 扩展版权声明，确保 ORGANIZATION_NAME 处理逻辑不会导致多余 .。
✅ 格式化注释块，确保适用于所有 C/C++ 代码风格。
✅ 适用于 C++ Header File 和 C++ Source File，保证一致性。

2.3.1 优化建议

如果你希望进一步增强这个模板，可以考虑增加 @details 和 @license：

增加 @details 。鼓励开发者写更详细的文档：

 * @details 该文件提供了 xxx 功能的实现

添加 @license。如果有开源需求，可以加上：

 *  @license MIT License

最终优化代码

/**
 * ==================================================
 *  @file ${FILE_NAME}
 *  @brief TODO 描述该文件的功能
 *  @author ${USER_NAME}
 *  @date ${YEAR}-${MONTH}-${DAY} ${TIME}
 *  @version 1.0
 *  
 *  @details 本文件包含...
 *  
#if ($ORGANIZATION_NAME && $ORGANIZATION_NAME != "")
 *  @copyright Copyright (c) $YEAR ${ORGANIZATION_NAME}#if (!$ORGANIZATION_NAME.endsWith(".")).#end All rights reserved.
#else
 *  @copyright Copyright (c) ${YEAR} ${USER_NAME}. All Rights Reserved.
#end
 *  
 *  @license MIT License
 * ==================================================
 */

2.3.2 最终优化总结

✅ 当前 C File Header.h 的优势

• 清晰的文件头部格式，易读、易维护。
• 自动填写文件名、作者、日期、时间，提高开发效率。
• 支持动态版权声明，适用于个人项目和公司项目。
• 支持 Doxygen 风格，可生成代码文档。

🔧 如何配置

1. 在 Settings → File and Code Templates 修改 C File Header.h。
2. 适用于 .h 和 .cpp 文件，确保所有新建文件都有标准化头部注释。
3. 可扩展：可以添加 @license、@details 等，增强代码文档质量。

这个 C File Header.h 既适用于 个人项目，也适用于 公司项目，是一个通用、高效的文件头部模板。这种优化后，每次新建 C/C++ 文件，都会自动添加标准化的文件头部注释，提高代码的可读性和团队协作效率。🚀

---

3. IntelliJ IDEA / PyCharm / WebStorm 的文件头部模板配置

3.1 IntelliJ IDEA（适用于 Java/Kotlin）

路径：File and Code Templates → Includes → File Header

示例（Java 文件头）：

/**
 * ==================================================
 *  This class ${NAME} is responsible for [功能描述].
 * 
 *  @author ${USER}
 *  @version 1.0
 * ==================================================
 */

3.2 PyCharm（适用于 Python）

示例（Python 文件头）：

"""
==================================================
 @file ${NAME}.py
 @brief TODO 描述该文件的功能
 @author ${USER}
 @date ${DATE} ${TIME}
 @version 1.0
#if ($ORGANIZATION_NAME && $ORGANIZATION_NAME != "")
 @copyright Copyright (c) $YEAR ${ORGANIZATION_NAME}. All rights reserved.
#else
 @copyright Copyright (c) ${YEAR} ${USER}. All Rights Reserved.
#end
==================================================
"""

总结

• CLion 重点适用于 C/C++，其 C File Header.h 可用于 .h 和 .cpp 文件。
• IntelliJ IDEA 适用于 Java/Kotlin，配置方式与 CLion 类似，但使用 File Header。
• PyCharm 适用于 Python，采用 # 作为注释符号，支持相同的变量替换。