我的C++编码规范

我对编码规范的理解

在我看来，编码规范不是死板的条条框框。写代码不只是让程序跑起来，更要保证代码可读、方便后续修改和团队协作。如果代码格式混乱、命名随意，不仅别人看不懂，一段时间后我自己再回看也很难快速理解逻辑。一套统一的编码规范，可以减少低级 bug，让代码整洁清晰。下面是我整理的 C++ 编码规范。

一、代码排版规范

代码排版像写字，工整整洁才方便自己和他人阅读修改。

1. 缩进规范

统一用4 个空格缩进，禁止使用 Tab 键；大括号不单独换行，紧跟语句后面；哪怕只有一行代码，也必须加大括号。
目的：分清代码层级，避免后续新增代码出错、逻辑混乱。

❌ 错误示例

// 错误：大括号换行、单行无大括号
if (num > 0)
    return true;

// 错误：使用Tab缩进、层级混乱
void test(){
  int a=1;
}

✅ 正确示例

// 函数写法
void testFunc() {
    // 4空格缩进
    int num = 10;
}

// 条件语句写法（单行也带大括号）
if (num > 0) {
    return true;
} else {
    return false;
}

// 循环语句写法
for (int i = 0; i < 10; i++) {
    cout << i << endl;
}

2. 空行使用规范

用空行分隔不同功能的代码，不要密密麻麻挤在一起。函数之间空 2 行，同一函数内不同逻辑、变量声明和执行代码之间空 1 行，禁止连续 3 行及以上空行。

❌ 错误示例

void func1() {
    int a=0;
    int b=1;
    a=a+b;
}

void func2() {
    // 连续空行过多
}

✅ 正确示例

#include <iostream>

// 全局变量
int max_num = 100;

// 函数1
void func1() {
    // 变量声明
    int a = 0;
    int b = 1;

    // 逻辑执行
    a = a + b;
}

// 函数2
void func2() {
    cout << "test" << endl;
}

3. 长语句换行规范

一行代码太长必须换行，在逗号、加减乘除、逻辑符号后换行，换行代码对齐，不拆分变量和方法。

❌ 错误示例

// 一行堆砌过长代码，不换行
int res=num1+num2+num3+num4+num5+num6;

// 拆分不合理、对齐混乱
int res = num1
+ num2 + num3;

✅ 正确示例

// 长表达式换行
int res = num1 + num2 
          + num3 + num4;

// 多参数函数换行
void calc(int a, int b, 
          int c, int d) {

}

// 复杂条件换行
if (a > 0 && 
    b < 100 && 
    c == 10) {

}

4. 空格使用规范

代码适当留空格，看着清爽，统一风格，不随心所欲加空格。
运算符、等号两边加空格；逗号后面加空格；if/for/while 关键字后加空格；数组括号、指针前后不加多余空格。

❌ 错误示例

int a=10+5;
test(1,2,3);
while(a<100){}
int * p = nullptr;
arr[ 0 ] = 10;

✅ 正确示例

int a = 10 + 5;
bool flag = (a > 0);

// 逗号后加空格
test(1, 2, 3);

// 指针写法
int* p = nullptr;

// 循环/条件空格
while (a < 100) {}

5. 无用代码清理规范

所有注释掉的旧代码、测试临时代码、没用到的函数 / 变量，直接删除，不要留在项目里。历史代码可以用 Git 查看，不用注释留存。

❌ 错误示例

// 废弃旧代码，禁止留存
// int oldSum(int a,int b){
//     return a-b;
// }

int sum(int a, int b) {
    return a + b;
}

✅ 正确示例

// 只保留有效代码
int sum(int a, int b) {
    return a + b;
}

二、代码注释规范

注释是解释为什么这么写，不是重复代码内容；代码改了，注释必须同步改，简洁不啰嗦。

1. 基础注释规则

1. 禁止一段代码里中英混写；
2. 注释和对应代码缩进对齐；
3. 单行解释用//，模块 / 大段复杂说明用/* */，函数说明用文档注释/** */。

2. 特殊场景注释

非常规代码（故意不写 break）必须加注释，避免别人误以为是 bug。

❌ 错误示例

// 无注释，他人看不懂逻辑
switch (state) {
    case 1:
        func1();
    case 2:
        func2();
        break;
}

✅ 正确示例

switch (state) {
    case 1:
        func1();
        // 故意穿透，无需break
        /* FALLTHROUGH */
    case 2:
        func2();
        break;
    default:
        break;
}

3. 函数注释规范

所有自定义函数上方写简短注释：功能、参数、返回值，方便调用。

❌ 错误示例

// 求和（无效注释，只是复述代码）
int sum(int a, int b) {
    return a + b;
}

✅ 正确示例

/**
 * @brief 计算两个整数的和
 * @param a 第一个整数
 * @param b 第二个整数
 * @return 两数之和
 */
int sum(int a, int b) {
    return a + b;
}

三、命名规范

变量、函数名字一眼看懂用途，不需要额外猜意思。

1. 变量、函数命名

• 局部变量：小写字母 + 下划线；
• 全局变量：加g_前缀；
• 静态变量：加s_前缀；
• 函数名：动词 + 名词，描述做什么操作；
• 布尔变量：用is_或has_开头。

❌ 错误示例

int a;        // 名字含义不明
void func();  // 不知道函数功能
bool flag;    // flag指代模糊

✅ 正确示例

int g_system_state;    // 全局变量
static int s_count;    // 静态变量
int buffer_size;       // 局部变量
bool is_ready;         // 布尔变量
int calculate_sum();   // 函数

2. 常量、宏、枚举命名

• 宏、枚举值：全部大写，下划线分隔；
• const 常量：使用k_前缀。

❌ 错误示例

#define num 10
enum mode {normal, debug};
const int maxUsers = 100;

✅ 正确示例

#define MAX_RETRIES (5)
enum MODE {MODE_NORMAL, MODE_DEBUG};
const int k_max_users = 100;

四、其他关键编码规范

1. 结构体成员排布

结构体里变量按占用内存从大到小排序，减少内存浪费。

❌ 错误示例

struct BadStruct {
    char c;
    int i;
    short s;
};

✅ 正确示例

struct GoodStruct {
    int i;
    short s;
    char c;
};

2. 变量初始化

定义变量的时候立刻给初始值，防止出现随机垃圾值。

❌ 错误示例

int counter;
char* buffer;
// 没有初始化，直接使用会出现随机值

✅ 正确示例

int counter = 0;
char* buffer = nullptr;

3. 运算符优先级

复杂表达式，多用括号明确计算顺序，不要靠默认优先级。

❌ 错误示例

result = a << 8 + b * c;

✅ 正确示例

result = (a << 8) + (b * c);

五、总结

我知道自己现在还只是大二，代码写得还不够规范，经常会出现缩进乱、命名随意、注释偷懒的问题。但我希望从现在开始，把这些规则养成习惯：写代码前先想清楚命名，写完后对照规范自查，用工具自动格式化，在写代码时主动按这套标准来。未来我会持续按照这份规范精进自己的代码技术，让自己写出的代码不仅能跑，还要好读、好改、经得起别人 review。

六、参考资料

《Code Styleguide — 优雅的编码规范》
Google 开源项目风格指南（Google C++ Style Guide） https://google.github.io/styleguide/cppguide.html