【C++ 注释与编码风格】单行注释、多行注释、代码规范

1. 什么是注释为什么需要注释注释是写给人看的而不是给计算机执行的。它们用于解释代码的意图、逻辑、注意事项帮助自己和他人理解代码。编译器会完全忽略注释所以注释不会影响程序的运行结果或性能。2. C 中的两种注释2.1 单行注释//从//开始到本行末尾的所有内容都是注释。#includeiostreamusingnamespacestd;intmain(){// 这是单行注释编译器会忽略这整行intage18;// 也可以放在语句后面解释变量含义cout年龄ageendl;// 输出年龄return0;}2.2 多行注释/* */从/*到*/之间的所有内容都是注释可以跨越多行。#includeiostreamusingnamespacestd;/* * 这是一个多行注释 * 通常用来写函数说明、文件头、算法思路等 * 这里可以写很长的描述 */intmain(){/* 也可以像这样单行使用 */coutHelloendl;return0;}2.3 注释的嵌套问题单行注释可以包含多行注释的起始符号但一般不这么做。多行注释不能嵌套多行注释因为第一个*/会结束注释。/* 外层注释开始 /* 内层注释 */// 这里的 */ 会结束外层注释导致编译错误错误代码*/正确做法避免多行注释嵌套如需嵌套改用单行注释。3. 注释在内存中的“存在感”编译过程大致如下源代码 (hello.cpp) → 预处理器 → 编译单元 → 编译器 → 目标代码 → 链接 → 可执行文件 包含注释 移除注释 无注释的代码 无注释的机器码内存模型讲解假设我们写了这样的代码intmain(){// 这是一个注释intx42;/* 多行注释 */returnx;}预处理器阶段将所有注释替换为一个空格或直接删除。上面的代码等效于intmain(){intx42;returnx;}编译阶段编译器只看到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_SIZE4.2 缩进与空格使用2 或 4 个空格缩进不要使用 Tab 键或设置编辑器将 Tab 转为空格。花括号{ }风格两种常见方式选一种保持一致。行末风格紧凑if(condition){do_something();}换行风格清晰if(condition){do_something();}4.3 行的长度每行代码不超过80 或 100 个字符超长时适当换行。// 不好的写法coutThis is a very long line that exceeds the limit and makes it hard to read on small screens or side-by-side diffsendl;// 好的写法coutThis is a very long line that exceeds the limit and makes it hard to read on small screens or side-by-side diffsendl;4.4 函数长度与职责一个函数只做一件事建议不超过 40-50 行。如果过长拆分为多个小函数。4.5 注释的最佳实践文件头注释说明文件名、作者、创建日期、用途。函数注释描述功能、参数、返回值、注意事项。复杂逻辑前解释为什么这样写而不是怎么写代码本身说明怎么做的。TODO 注释标记待完成的工作例如// TODO(zhang): 优化这里的内存使用。不要写废话注释intcount0;// 将 count 赋值为 0 ← 废话代码已经说明4.6 一个规范的代码示例/** * file calculator.cpp * brief 实现一个简单的加法计算器 * author Alice * date 2025-01-15 */#includeiostreamusingnamespacestd;// 常量定义constintkMaxOperand1000;/** * brief 两个整数相加并检查溢出简单版 * param a 第一个加数 * param b 第二个加数 * return 两数之和 */intAdd(inta,intb){// 简单的溢出检查仅示意if(akMaxOperand||bkMaxOperand){cerrError: operand exceeds limitendl;return0;}returnab;}intmain(){intx10,y20;intresultAdd(x,y);coutResult: resultendl;return0;}5. 常见错误与避坑错误说明注释中的/*和*/不匹配导致大段代码被意外注释或编译错误在字符串中使用//或/*它们是字符串字面量的一部分不会被当作注释例如http://example.com没问题注释太多或太少适当平衡不要过度注释也不要完全不注释混用 Tab 和空格不同编辑器显示宽度不同导致排版混乱。统一用空格。6. 练习题题目下面是一段风格混乱、缺少注释的 C 代码。请你添加合适的注释文件头、函数功能、关键变量。按照规范重新命名变量和函数使用 snake_case 或 PascalCase。修正缩进和空格问题。原始代码#includeiostreamusingnamespacestd;intF(inta,intb){intcab;returnc;}intmain(){intx,y;cinxy;coutF(x,y)endl;return0;}上期练习答案#includeiostream#includeiomanipusingnamespacestd;intmain(){doublenum;cout请输入一个浮点数;cinnum;cout默认格式numendl;coutfixedsetprecision(3)固定3位小数numendl;coutscientificsetprecision(4)科学计数法numendl;intn;cout请输入一个整数;cinn;// 恢复默认浮点格式可选因为后面只输出整数coutdefaultfloat;coutsetfill(0);// 设置填充字符为 0cout十进制setw(8)decnendl;cout十六进制setw(8)hexnendl;cout八进制setw(8)octnendl;return0;}总结注释是写给人的说明书编译器完全忽略它。良好的编码风格命名、缩进、行宽、注释规范能让代码更易读、易维护。记住代码是写给人看的顺便让机器执行。下一篇文章我们将学习变量与常量开始存储数据啦请动手改写上面的混乱代码并运行验证结果。