《高质量 C++/C 编程指南》注释规范 + VS2022 模板-育师

本文简单整理了一下《高质量 C++/C 编程指南》注释规范，并非原创且作者在书中已明确准许引用

一、核心注释规则（原文引用 + 极简解读）

1. 位置要求

【规则 2-7-6】注释应与其描述的代码相近，放上方（长注）或右方（短注），不可放下方。

解读：
✅ 单行代码注释：简短注释放右侧（与代码隔 1-2 个空格），长注释放上方；
❌ 禁止放代码下方（易被忽略，违背自上而下的阅读逻辑）；
✅ 示例：// 修改 int 变量 4 字节值（上方注释）*pi = 0; // 赋值为 0（右侧注释）

2. 内容要求

【规则 2-7-1】注释是 “提示” 而非 “解释”，准确简洁，无用则删。

解读：
无需注释显而易见的代码（如int n = 0;）；
需注释场景：复杂逻辑、特殊算法、边界条件、指针 / 内存操作等（如 char * 解引用修改单字节的大小端逻辑）。

3. 格式要求

【规则 2-7-5】单行用//，多行用/* ... */，风格统一。

解读：
VS2022 兼容 C 语言下的//单行注释，推荐优先使用；
注释内容避免冗余（如不写 “给 n 赋值”，可写 “初始化 int 变量为十六进制值”）。

4. 必加场景

【规则 2-7-2】每个源文件头部必须加注释，说明文件名称、功能、作者、创建日期、版本 / 修改记录。

解读：
示例（C 语言）：
/** 文件名称：mem_modify.c
功能描述：演示指针解引用修改不同字节长度的内存值
作者：XXX
创建日期：2025-12-16**/

【规则 2-7-3】函数（尤其对外接口）必须加注释，说明功能、参数（输入 / 输出）、返回值、注意事项。

解读：
示例（C 语言）：
// 功能：通过 char 指针修改 int 变量首字节
// 参数：pc - 指向 int 变量首字节的 char 指针；val - 要修改的单字节值
// 注意：基于 x86 小端架构，仅修改低地址字节
void modifyCharByte(char* pc, char val) { *pc = val; }

【规则 2-7-5】项目注释格式需统一：单行注释用//，多行注释用/* ... */；注释首字符大写。

解读：
VS2022 兼容 C 语言下的//单行注释，推荐优先使用；注释内容避免冗余（如不写 “给 n 赋值”，可写 “初始化 int 变量为十六进制值”）。

二、VS2022 示例

1. 源文件头部注释模板（规则 2-7-2）

/* * 文件名称：xxx.c（替换为实际文件名，如mem_modify.c） * 功能描述：【简要说明文件核心功能，如：演示指针解引用修改int变量不同字节长度的值】 * 作 者：【你的姓名/昵称】 * 创建日期：【YYYY-MM-DD，如2025-12-16】 * 修改记录：【无修改则写“无”；有修改则写“YYYY-MM-DD - 姓名 - 修改内容”】 * 注意事项：【可选，如：基于x86/x64小端架构，char*解引用仅修改int变量低地址首字节】 */

2. 函数注释模板（规则 2-7-3）

// 功能：【核心作用，如：通过int指针修改变量全部4字节值】 // 参数：【输入/输出参数说明，无则写“无”；如：n - 待修改的int型变量（输入/输出）】 // 返回值：【如：int - 0表示执行成功】 // 注意事项：【可选，如：解引用会覆盖变量所有4字节内容】 int modifyIntAllByte(int* n, int val) { *n = val; return 0; }

3. 单行 / 代码块注释模板（规则 2-7-6、2-7-1、2-7-5）

#include <stdio.h> /* * 文件名称：mem_modify.c * 功能描述：演示int*和char*解引用修改int变量不同字节长度的效果 * 作 者：XXX * 创建日期：2025-12-16 * 修改记录：无 * 注意事项：VS2022 x86/x64环境下为小端序，char*指向int变量低地址首字节 */ // 功能：通过int指针修改变量全部4字节值 // 参数：无 // 返回值：int - 0表示执行成功 int main() { // 初始化4字节int变量，十六进制值：0x11223344（小端存储：0x44→0x33→0x22→0x11） int n = 0x11223344; int* pi = &n; // 定义指向int变量的指针（右侧简短注释） *pi = 0; // 解引用修改n的全部4字节为0（右侧注释说明操作） printf("n = 0x%x\n", n); // 强制输出0x前缀的十六进制值，预期结果：0x0 // 重新初始化变量，用于演示char*解引用效果 n = 0x11223344; char* pc = (char*)&n; // 强制转换为char*，仅指向n的首字节（低地址） *pc = 0; // 仅修改n的首字节为0，其余3字节保留，预期结果：0x11223300 printf("n = 0x%x\n", n); return 0; }