1. 什么是注释?为什么需要注释?

注释是写给人看的,而不是给计算机执行的。它们用于解释代码的意图、逻辑、注意事项,帮助自己和他人理解代码。编译器会完全忽略注释,所以注释不会影响程序的运行结果或性能。

2. C++ 中的两种注释

2.1 单行注释 //

从 // 开始到本行末尾的所有内容都是注释。

#include <iostream>
using namespace std;

int main() {
    // 这是单行注释,编译器会忽略这整行
    int age = 18;  // 也可以放在语句后面,解释变量含义
    cout << "年龄:" << age << endl;  // 输出年龄
    return 0;
}

2.2 多行注释 /* */

从 /* 到 */ 之间的所有内容都是注释,可以跨越多行。

#include <iostream>
using namespace std;

/*
 * 这是一个多行注释
 * 通常用来写函数说明、文件头、算法思路等
 * 这里可以写很长的描述
 */
int main() {
    /* 也可以像这样单行使用 */
    cout << "Hello" << endl;
    return 0;
}

2.3 注释的嵌套问题

  • 单行注释可以包含多行注释的起始符号,但一般不这么做。
  • 多行注释不能嵌套多行注释,因为第一个 */ 会结束注释。
/* 外层注释开始
   /* 内层注释 */   // 这里的 */ 会结束外层注释,导致编译错误
   错误代码 */

正确做法:避免多行注释嵌套,如需嵌套,改用单行注释。

3. 注释在内存中的“存在感”

编译过程大致如下:

源代码 (hello.cpp)   →   预处理器   →   编译单元   →   编译器   →   目标代码   →   链接   →   可执行文件
  包含注释                移除注释         无注释的代码              无注释的机器码

内存模型讲解:

假设我们写了这样的代码:

int main() {
    // 这是一个注释
    int x = 42; /* 多行注释 */
    return x;
}
  1. 预处理器阶段:将所有注释替换为一个空格(或直接删除)。上面的代码等效于:
    int main() { int x = 42; return x; }
    
  2. 编译阶段:编译器只看到 int x = 42;,完全不知道有注释存在。
  3. 内存中的最终结果:可执行文件(.exe 或二进制文件)中不包含任何注释。注释只存在于源代码中,占用的是硬盘上的源文件空间,而不是运行时内存。

🔍 关键点:注释不会增加程序的运行内存占用,也不会影响执行速度。放心大胆写注释!

4. 编码风格与代码规范

好的编码风格让代码像优美的文章,降低维护成本。以下是最常用的规范(参考 Google C++ Style Guide 和国内大厂标准)。

4.1 命名规范

类型风格示例
变量名小写字母 + 下划线 (snake_case)student_name, max_value
函数名小写字母 + 下划线get_user_info(), calculate_sum()
类名大驼峰 (PascalCase)StudentManager, FileParser
常量k 前缀 + 大驼峰 或 全大写+下划线kMaxSize, PI
宏全大写 + 下划线MAX_BUFFER_SIZE

4.2 缩进与空格

  • 使用 2 或 4 个空格 缩进(不要使用 Tab 键,或设置编辑器将 Tab 转为空格)。
  • 花括号 { } 风格:两种常见方式,选一种保持一致。
    • 行末风格(紧凑):
      if (condition) {
          do_something();
      }
      
    • 换行风格(清晰):
      if (condition)
      {
          do_something();
      }
      

4.3 行的长度

每行代码不超过 80 或 100 个字符,超长时适当换行。

// 不好的写法
cout << "This is a very long line that exceeds the limit and makes it hard to read on small screens or side-by-side diffs" << endl;

// 好的写法
cout << "This is a very long line that exceeds the limit "
     << "and makes it hard to read on small screens or side-by-side diffs" << endl;

4.4 函数长度与职责

一个函数只做一件事,建议不超过 40-50 行。如果过长,拆分为多个小函数。

4.5 注释的最佳实践

  • 文件头注释:说明文件名、作者、创建日期、用途。
  • 函数注释:描述功能、参数、返回值、注意事项。
  • 复杂逻辑前:解释为什么这样写,而不是怎么写(代码本身说明怎么做的)。
  • TODO 注释:标记待完成的工作,例如 // TODO(zhang): 优化这里的内存使用。
  • 不要写废话注释:
    int count = 0;  // 将 count 赋值为 0   ← 废话,代码已经说明
    

4.6 一个规范的代码示例

/**
 * @file calculator.cpp
 * @brief 实现一个简单的加法计算器
 * @author Alice
 * @date 2025-01-15
 */

#include <iostream>
using namespace std;

// 常量定义
const int kMaxOperand = 1000;

/**
 * @brief 两个整数相加,并检查溢出(简单版)
 * @param a 第一个加数
 * @param b 第二个加数
 * @return 两数之和
 */
int Add(int a, int b) {
    // 简单的溢出检查(仅示意)
    if (a > kMaxOperand || b > kMaxOperand) {
        cerr << "Error: operand exceeds limit" << endl;
        return 0;
    }
    return a + b;
}

int main() {
    int x = 10, y = 20;
    int result = Add(x, y);
    cout << "Result: " << result << endl;
    return 0;
}

5. 常见错误与避坑

错误说明
注释中的 /* 和 */ 不匹配导致大段代码被意外注释或编译错误
在字符串中使用 // 或 /*它们是字符串字面量的一部分,不会被当作注释,例如 "http://example.com" 没问题
注释太多或太少适当平衡,不要过度注释,也不要完全不注释
混用 Tab 和空格不同编辑器显示宽度不同,导致排版混乱。统一用空格。

6. 练习题

题目:下面是一段风格混乱、缺少注释的 C++ 代码。请你:

  1. 添加合适的注释(文件头、函数功能、关键变量)。
  2. 按照规范重新命名变量和函数(使用 snake_case 或 PascalCase)。
  3. 修正缩进和空格问题。

原始代码:

#include <iostream>
using namespace std;
int F(int a,int b){
int c=a+b;
return c;}
int main(){int x,y;cin>>x>>y;cout<<F(x,y)<<endl;return 0;}

上期练习答案

#include <iostream>
#include <iomanip>
using namespace std;

int main() {
    double num;
    cout << "请输入一个浮点数:";
    cin >> num;

    cout << "默认格式:" << num << endl;
    cout << fixed << setprecision(3) << "固定3位小数:" << num << endl;
    cout << scientific << setprecision(4) << "科学计数法:" << num << endl;

    int n;
    cout << "请输入一个整数:";
    cin >> n;

    // 恢复默认浮点格式(可选,因为后面只输出整数)
    cout << defaultfloat;
    cout << setfill('0');  // 设置填充字符为 '0'
    cout << "十进制:" << setw(8) << dec << n << endl;
    cout << "十六进制:" << setw(8) << hex << n << endl;
    cout << "八进制:" << setw(8) << oct << n << endl;

    return 0;
}

总结:注释是写给人的说明书,编译器完全忽略它。良好的编码风格(命名、缩进、行宽、注释规范)能让代码更易读、易维护。记住:代码是写给人看的,顺便让机器执行。下一篇文章我们将学习变量与常量,开始存储数据啦!

请动手改写上面的混乱代码,并运行验证结果。

Logo

北京人形旗下天工造物具身智能开源社区,聚焦具身天工与慧思开物两大平台

更多推荐