【C++ 注释与编码风格】单行注释、多行注释、代码规范
·
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;
}
- 预处理器阶段:将所有注释替换为一个空格(或直接删除)。上面的代码等效于:
int main() { int x = 42; return x; } - 编译阶段:编译器只看到
int x = 42;,完全不知道有注释存在。 - 内存中的最终结果:可执行文件(.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++ 代码。请你:
- 添加合适的注释(文件头、函数功能、关键变量)。
- 按照规范重新命名变量和函数(使用 snake_case 或 PascalCase)。
- 修正缩进和空格问题。
原始代码:
#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;
}
总结:注释是写给人的说明书,编译器完全忽略它。良好的编码风格(命名、缩进、行宽、注释规范)能让代码更易读、易维护。记住:代码是写给人看的,顺便让机器执行。下一篇文章我们将学习变量与常量,开始存储数据啦!
请动手改写上面的混乱代码,并运行验证结果。
更多推荐
所有评论(0)