17370845950

写好注释的核心是准确传达代码意图，提升可维护性；优先用//作单行注释，保持简洁清晰；多行说明用/.../，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等标签。

• 示例：

  /**  
       * @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时，把注释准确性列入检查项：是否准确？是否冗余？是否遗漏关键约束？

基本上就这些。注释不是越多越好，而是刚好够用、准确、可持续。保持克制，尊重读者的时间。