C++ 注释

注释是写在源码里、编译时会被跳过的文字，不改变程序的运行结果。它用来向读者说明函数怎么用、参数有哪些限制，或解释代码里不那么直观的选择；有时也用来暂时让某段实现不参与编译。C++ 提供单行注释 // 与块注释 /* */。日常以 // 为主，块注释多用于暂时关掉一段代码。名称已经说清含义时（例如 empty()、size()），不必再写复述声明的注释。本节说明两种写法的规则，以及怎样让注释真正有助于阅读和维护。

单行注释

从 // 到行尾均为注释。适合行尾备注或连续若干行说明：

#include <iostream>
#include <string>
#include <vector>

int main() {
    std::vector<std::string> names{"Ada", "Bjarne"};
    // 只输出长度，不打印每个名字
    std::cout << names.size() << "\n";
    return 0;
}

输出：

2

跨多行时每行单独写 //，或改用块注释。

块注释与嵌套

/* 与 */ 之间可跨行。块注释不能嵌套：内层 /* 无效，第一个 */ 会结束整段，后续源码可能被误当成注释。临时屏蔽大段代码时，优先用编辑器折叠或版本管理，不要叠多层 /*。

/*
 * area：宽、高均为正数时结果有效。
 * 负值未在此函数内校验，由调用方保证。
 */
double area(double w, double h) {
    return w * h;
}

注释应写什么

• 用法与限制：参数取值范围、返回值含义、失败时是否抛异常，而不是复述标识符。
• 不易看出的选择：为何用引用而不拷贝、为何不用范围 for 等。
• 已知问题：平台相关行为、缺陷编号。

若逻辑只能靠注释才能看懂，应先改命名与结构。成员函数名 empty()、size() 本身已表达含义，不必再写返回是否为空这类复述。

不要用注释关掉大段实现

块注释不能嵌套，用 /* */ 包住已含块注释的代码会提前结束。临时排除编译的大段实现，可用条件编译：

#if 0
    // 此段不参与编译，内部即使出现 /* */ 也不受影响
    legacy_draw();
#endif

#if 0 是预处理，不是注释；把开关改为 1 即可重新编译该段。字符串字面量里的 // 或 /* 不会开始注释，例如 URL "https://example.com" 中的斜杠属于字符。

与文档工具

部分项目用 Doxygen 解析 /// 或 /** */，从注释生成接口文档。预处理器指令（#include）不是注释。初学掌握 // 与 /* */ 即可；把用法写清楚后，实现细节交给代码本身。

本节说明了 C++ 中注释的写法、限制以及与预处理的区别。下一节介绍类型转换：隐式转换与 static_cast。