【C++学习第十讲】C++ 注释

一、注释的解释说明

在编写程序时，注释是一个非常有价值的工具，可以提高代码的可读性和可维护性。以下是一些建议和最佳实践，可以帮助您有效地使用注释：

1.1 文件注释

在每个源文件的开头，添加一段文件级注释，描述文件的目的、作者、日期等信息。这有助于其他开发人员理解文件的背景和上下文。

/*
 * 文件名: example.cpp
 * 作者: John Doe
 * 创建日期: 2023-05-22
 * 描述: 这个文件包含了一个示例程序的实现。
 */

1.2 函数注释

在每个函数定义前添加注释，描述函数的功能、参数、返回值和任何特殊注意事项。这样可以使其他人更容易理解函数的作用和用法。

/*
 * 函数名: calculateSum
 * 描述: 计算两个整数的和。
 * 参数:
 *   - num1: 第一个整数
 *   - num2: 第二个整数
 * 返回值: 两个整数的和
 */
int calculateSum(int num1, int num2) {
    // 函数实现...
}

1.3 代码段注释

在代码段上方或旁边添加注释，解释该代码段的目的、算法或者关键步骤。这对于复杂的逻辑、算法或者需要特别注意的代码非常有用。

int x = 10;
int y = 20;

// 检查 x 是否大于 y
if (x > y) {
    // 如果 x 大于 y，则执行某些操作
    // ...
} else {
    // 否则执行其他操作
    // ...
}

1.4 临时禁用代码

注释还可以用于临时禁用代码，以便调试或测试其他部分的代码。这在定位问题或逐步构建功能时非常有用。

// int result = someFunctionCall();  // 暂时禁用该行代码

1.5 注意事项注释

如果有一些需要特别注意的事项、已知问题或待解决的问题，可以在相关代码处添加注释，提醒自己或其他人注意。

int divisor = 0;
int result = 0;

// 注意：除数不能为零
if (divisor != 0) {
    result = 10 / divisor;
}

总的来说，注释应该清晰、简明扼要，并且要与代码保持同步。良好的注释可以帮助团队合作、提高代码的可读性和可维护性，因此在编写代码时，注释是一个重要的实践。

二、C++ 注释

C++ 支持单行注释和多行注释。注释中的所有字符会被 C++ 编译器忽略。

C++ 注释一般有两种：

• 单行注释

单行注释以双斜杠（//）开头，注释内容从双斜杠后面开始，一直延伸到该行的结尾。例如：

// 这是一个单行注释
int x = 10; // 可以在代码行的末尾添加注释

• 多行注释

多行注释也被称为块注释，它以斜杠星号（/）开头，以星号斜杠（/）结尾。多行注释可以跨越多行，并且可以注释掉一整个代码块。例如：

/* 这是一个
   多行注释 */
int y = 20;
/* 这是另一个
   多行注释
   涵盖多行 */

2.1 单行注释的实例

#include <iostream>
using namespace std;
 
int main() {
  // 这是一个注释
  cout << "Hello World!";
  return 0;
}

输出结果为：

Hello World!
D:\C++CodeProject\Project2\x64\Debug\Project2.exe (进程 66780)已退出，代码为 0。
按任意键关闭此窗口. . .

也可以放在语句后面：

#include <iostream>
using namespace std;
 
int main()
{
   cout << "Hello World!"; // 输出 Hello World!
 
   return 0;
}

Hello World!
D:\C++CodeProject\Project2\x64\Debug\Project2.exe (进程 103080)已退出，代码为 0。
按任意键关闭此窗口. . .

当上面的代码被编译时，编译器会忽略 // 这是一个注释 和 // 输出 Hello World!，最后会产生以下结果：

Hello World!

2.2 多行注释的实例

C++ 注释以 /* 开始，以 */ 终止。例如：

#include <iostream>
using namespace std;
 
int main() {
    /* 这是注释 */
 
    /* C++ 注释也可以
     * 跨行
     */ 
    cout << "Hello World!";
    return 0;
}

在 /* 和 / 注释内部，// 字符没有特殊的含义。在 // 注释内，/ 和 */ 字符也没有特殊的含义。因此，您可以在一种注释内嵌套另一种注释。例如：

#include <iostream>
using namespace std;

int main() {
    /* 这是注释 */

    /* C++ 注释也可以
     * 跨行
     */
    /*
    cout << "Hello World!"; // 输出hello world!
    */
    
    return 0;
}