C++ 注释

注释是用于解释代码的文字，编译器会忽略注释内容。在 C++ 中，有两种注释方式：单行注释和多行注释。良好的注释习惯可以提高代码的可读性和可维护性。

1. 单行注释

使用//开头，注释从//开始到行尾结束：

cpp

// 这是一个单行注释
int a = 10;  // 这也是一个单行注释，说明变量 a 的值

// 计算两个数的和
int sum = a + b;

1.1 使用场景

单行注释通常用于：

解释单行代码的功能
说明变量的用途
标记重要的代码段
临时禁用某行代码

2. 多行注释

使用/*开头，*/结尾，注释可以跨越多行：

cpp

/*
这是一个多行注释
可以跨越多行
用于详细解释代码
*/
int b = 20;

/*
函数功能：计算两个数的最大值
参数：
    a: 第一个整数
    b: 第二个整数
返回值：
    两个数中的最大值
*/
int max(int a, int b) {
    return (a > b) ? a : b;
}

2.1 使用场景

多行注释通常用于：

详细解释函数的功能
说明复杂的算法
提供文件头信息
临时禁用多行代码

3. 注释的最佳实践

3.1 注释应该解释"为什么"而不是"是什么"

好的注释应该解释代码的意图和设计决策，而不是简单地重复代码：

cpp

// 不好的注释
int a = 10;  // 将 a 赋值为 10

// 好的注释
int a = 10;  // 设置默认超时时间为 10 秒

3.2 保持注释简洁明了

注释应该简洁明了，避免冗长：

cpp

// 不好的注释
// 这个函数的作用是计算两个数字的和，然后将结果返回给调用者
int add(int a, int b) {
    return a + b;
}

// 好的注释
// 计算两个数的和
int add(int a, int b) {
    return a + b;
}

3.3 保持注释与代码同步

当代码修改时，相应的注释也应该更新：

cpp

// 计算两个数的和
int add(int a, int b) {
    return a + b;
}

// 如果修改了函数功能，注释也应该更新
// 计算三个数的和
int add(int a, int b, int c) {
    return a + b + c;
}

3.4 避免无意义的注释

不要添加无意义的注释：

cpp

// 不好的注释
int a = 10;  // 定义变量 a
int b = 20;  // 定义变量 b

// 好的做法
int a = 10;  // 学生年龄
int b = 20;  // 课程数量

4. 文件头注释

在每个源文件的开头，通常添加文件头注释，说明文件的基本信息：

cpp

/*
 * 文件名：main.cpp
 * 描述：主程序文件
 * 作者：张三
 * 创建日期：2024-03-15
 * 最后修改：2024-03-20
 */

#include <iostream>

int main() {
    std::cout << "Hello, World!" << std::endl;
    return 0;
}

5. 函数注释

为每个函数添加注释，说明函数的功能、参数和返回值：

cpp

/*
 * 函数功能：计算两个数的最大公约数
 * 参数：
 *   a: 第一个正整数
 *   b: 第二个正整数
 * 返回值：
 *   a 和 b 的最大公约数
 */
int gcd(int a, int b) {
    while (b != 0) {
        int temp = b;
        b = a % b;
        a = temp;
    }
    return a;
}

6. 代码段注释

对于复杂的代码段，添加注释说明其逻辑：

cpp

// 使用快速排序算法对数组进行排序
void quickSort(int arr[], int low, int high) {
    if (low < high) {
        // 选择基准元素并分区
        int pi = partition(arr, low, high);
        
        // 递归排序左子数组
        quickSort(arr, low, pi - 1);
        
        // 递归排序右子数组
        quickSort(arr, pi + 1, high);
    }
}

7. TODO 注释

使用 TODO 注释标记需要完成的任务：

cpp

// TODO: 实现错误处理
void process_data() {
    // 数据处理代码
}

// TODO: 优化算法性能
void calculate() {
    // 计算代码
}

8. FIXME 注释

使用 FIXME 注释标记需要修复的问题：

cpp

// FIXME: 这里存在内存泄漏问题
void process() {
    int* ptr = new int[100];
    // 使用 ptr
    // 忘记释放内存
}

// FIXME: 边界条件处理不正确
int get_element(int arr[], int size, int index) {
    return arr[index];  // 没有检查 index 是否越界
}

9. HACK 注释

使用 HACK 注释标记临时的、不优雅的解决方案：

cpp

// HACK: 临时解决方案，需要重构
void workaround() {
    // 不优雅的代码
}

10. 注释的格式

保持注释的格式一致，提高代码的可读性：

cpp

// 好的格式
// 计算圆的面积
double calculate_area(double radius) {
    return 3.14159 * radius * radius;
}

// 不好的格式
//计算圆的面积
double calculate_area(double radius) {
    return 3.14159 * radius * radius;
}

11. 示例：综合运用

现在，让我们看一个综合运用注释的例子：

cpp

/*
 * 文件名：student.cpp
 * 描述：学生管理系统
 * 作者：张三
 * 创建日期：2024-03-15
 */

#include <iostream>
#include <string>

// 定义学生结构体
struct Student {
    std::string name;  // 学生姓名
    int id;            // 学生 ID
    float gpa;         // 学生 GPA
};

/*
 * 函数功能：计算学生的平均 GPA
 * 参数：
 *   students: 学生数组
 *   count: 学生数量
 * 返回值：
 *   平均 GPA
 */
float calculate_average_gpa(Student students[], int count) {
    float sum = 0.0f;
    
    // 遍历所有学生，累加 GPA
    for (int i = 0; i < count; i++) {
        sum += students[i].gpa;
    }
    
    // 计算平均值
    return sum / count;
}

/*
 * 函数功能：打印学生信息
 * 参数：
 *   student: 学生对象
 */
void print_student(const Student& student) {
    std::cout << "姓名: " << student.name << std::endl;
    std::cout << "ID: " << student.id << std::endl;
    std::cout << "GPA: " << student.gpa << std::endl;
}

int main() {
    // 创建学生数组
    const int NUM_STUDENTS = 3;
    Student students[NUM_STUDENTS];
    
    // 初始化学生数据
    students[0] = {"张三", 1001, 3.8f};
    students[1] = {"李四", 1002, 3.5f};
    students[2] = {"王五", 1003, 3.9f};
    
    // 打印所有学生信息
    std::cout << "学生信息：" << std::endl;
    for (int i = 0; i < NUM_STUDENTS; i++) {
        print_student(students[i]);
        std::cout << std::endl;
    }
    
    // 计算并打印平均 GPA
    float avg_gpa = calculate_average_gpa(students, NUM_STUDENTS);
    std::cout << "平均 GPA: " << avg_gpa << std::endl;
    
    // TODO: 添加学生添加和删除功能
    // FIXME: 需要添加输入验证
    
    return 0;
}

小结

C++ 的注释包括：

单行注释：使用//，适用于简短的注释
多行注释：使用/* */，适用于较长的注释
注释的最佳实践：
- 解释"为什么"而不是"是什么"
- 保持简洁明了
- 保持与代码同步
- 避免无意义的注释
特殊注释：
- 文件头注释
- 函数注释
- TODO 注释
- FIXME 注释
- HACK 注释

良好的注释习惯可以提高代码的可读性和可维护性，是优秀程序员的重要素质之一。在接下来的章节中，我们将学习 C++ 的数据类型。

C++ 注释 ​

1. 单行注释 ​

1.1 使用场景 ​

2. 多行注释 ​

2.1 使用场景 ​

3. 注释的最佳实践 ​

3.1 注释应该解释"为什么"而不是"是什么" ​

3.2 保持注释简洁明了 ​

3.3 保持注释与代码同步 ​

3.4 避免无意义的注释 ​

4. 文件头注释 ​

5. 函数注释 ​

6. 代码段注释 ​

7. TODO 注释 ​

8. FIXME 注释 ​

9. HACK 注释 ​

10. 注释的格式 ​

11. 示例：综合运用 ​

小结 ​