写好注释的核心是准确传达代码意图，提升可维护性；优先用//作单行注释，保持简洁清晰；多行说明用/.../，Doxygen文档用/*.../并规范标签；注释须随代码同步更新，避免过时或冗余。
写好注释不是为了凑数，而是让别人（包括未来的你）能快速理解代码意图。C++本身不强制注释风格，但统一、简洁、有信息量的注释能极大提升可维护性。
单行注释用//，紧跟代码逻辑，不悬空
推荐优先使用//，它语义清晰、视觉轻量，适合说明某一行或紧邻几行的目的。
- 写在代码上方或行尾，但避免“贴太近”造成阅读干扰：
int count = 0; // 初始化计数器（✅）int count = 0;//初始化计数器（❌ 缺少空格） - 不要为显而易见的操作加注释，比如
int i = 0; // 初始化i——除非i的初始值有特殊含义（如哨兵值-1） - 函数内部关键分支、边界处理、非常规写法建议加//说明：
if (ptr == nullptr) return -1; // 空指针提前返回，调用方需检查
多行注释用/* ... */，仅用于大段说明或临时屏蔽
/* ... */适合文件头、复杂算法说明、或需要跨多行解释的场景，但别嵌套、也别滥用。
- 文件开头可用/* ... */写模块说明（作者、功能、注意事项）：
/* * @file parser.h * @brief JSON片段解析器，支持嵌套对象但不校验UTF-8 * @warning 不线程安全，多线程请加锁 */ - 避免用/* ... */给函数体逐行注释——改用多个//更清晰
- 调试时临时注释大段代码可以用/* ... */，但提交前务必清理，尤其不能留“半截”注释
函数文档用Doxygen风格，保持结构一致
如果项目用Doxygen生成API文档，函数上方统一用/** ... */块，并包含@brief、@param、@return等标签。
立即学习“C++免费学习笔记（深入）”；
- 示例：
/** * @brief 查找数组中第一个大于target的元素下标 * @param arr 有序整数数组（升序），非空 * @param size 数组长度，> 0 * @param target 搜索目标值 * @return 下标（0~size-1），未找到返回size */ int upper_bound(const int* arr, int size, int target); - 参数名必须与函数声明严格一致，类型和约束写清楚（比如“非空”、“不可为nullptr”）
- 不写废话，比如“本函数用于查找”——
@brief本身已表明这是简介
注释要随代码更新，过期注释比没注释更危险
逻辑改了但注释没动，会误导阅读者，甚至引发误修。把注释当作代码的一部分来维护。
- 修改条件判断时，顺手更新对应的//说明；重构函数后，重写其Doxygen文档
- 遇到“这里为什么这么写？”的疑问，先查注释——如果没有，补上；如果写了但看不懂，重写
- Code Review时，把注释准确性列入检查项：是否准确？是否冗余？是否遗漏关键约束？
基本上就这些。注释不是越多越好，而是刚好够用、准确、可持续。保持克制，尊重读者的时间。
