C 语言编写规范

C 语言编写规范

基于 C 语言编程的行业标准与最佳实践，以下是一份系统化的 ‌C 语言编写规范‌。
这份规范旨在提升代码的可读性、可维护性及安全性， 适用于大多数嵌入式、系统级及应用层 C 语言项目。

1.命名规范 (Naming Conventions)

命名是代码可读性的核心。 原则是：‌见名知意‌，避免歧义，保持风格统一。

1.1 通用规则

字符集‌：仅使用字母 (a-z, A-Z)、数字 (0-9) 和下划线 (_)。
首字符‌：必须以字母或下划线开头，‌严禁‌以数字开头。
关键字‌：禁止使用 C 语言保留字（如 int, struct, return 等）。
大小写敏感‌：C 语言区分大小写，Count 和 count 是不同的标识符。
避免混淆‌：避免使用易混淆字符组合，如 l (小写L) 和 1 (数字1)，O (大写O) 和 0 (数字0)。

1.2 具体元素命名风格

元素类型	推荐风格	示例	说明
‌宏/常量‌	UPPER_SNAKE_CASE	MAX_BUFFER_SIZE#define PI 3.14	全大写，单词间用下划线分隔。
‌变量/函数‌	snake_case	user_countcalculate_sum()	全小写，单词间用下划线分隔。这是 C 语言最主流的风格。
‌类型/结构体‌	PascalCase 或 snake_case_t	StudentInfolist_node_t	结构体名通常首字母大写；typedef 别名常加 _t 后缀。
‌全局变量‌	g_ + snake_case	g_system_status	添加 g_ 前缀以明确其全局作用域，慎用全局变量。
‌静态变量‌	s_ + snake_case	s_retry_count	添加 s_ 前缀表示文件内静态可见。
‌布尔变量‌	is_ / has_ + ...	is_validhas_permission	清晰表达真假状态。

2. 代码格式与布局 (Code Formatting)

良好的视觉结构能降低认知负荷。

2.1 缩进与空格

• ‌缩进‌：统一使用 ‌4 个空格‌ 进行缩进，‌禁止‌使用 Tab 键（或在编辑器中设置为“Tab 转 4 空格”）。

• 空格使用‌：

1. 关键字后加空格：if (condition)，while (i < 10)。
2. 运算符两侧加空格：a = b + c;，x == y。
3. 逗号后加空格：func(a, b, c);。
4. 指针声明：int *ptr;（星号靠近类型或变量名均可，但需项目内统一，推荐靠近变量名以强调指针属性，或靠近类型以强调类型，目前 Linux 内核风格倾向于 int *ptr）。

2.2 括号风格

推荐 ‌Allman 风格‌ 或 ‌K&R 风格‌，项目内必须统一。

‌Allman 风格‌（推荐，结构清晰）：左大括号独占一行。

if (condition)
{
    do_something();
}
else
{
    do_other_thing();
}

‌K&R 风格‌（紧凑）：左大括号在行尾。

if (condition) {
    do_something();
} else {
    do_other_thing();
}

2.3 行宽与换行

• ‌行宽限制‌：每行代码建议不超过 ‌80‌ 或 ‌120‌ 个字符。

• ‌长表达式换行‌：在运算符处换行，并保持后续行缩进。

int result = long_variable_name_1 + 
             long_variable_name_2 + 
             long_variable_name_3;

3. 注释规范 (Comments)

注释应解释 ‌“为什么”‌ 而不是 ‌“是什么”‌（代码本身应展示是什么）。

3.1 文件头注释

每个源文件 (.c/.h) 头部应包含简要说明。

/**
 * @file    list.c
 * @brief   链表基本操作实现
 * @author  John Doe
 * @date    2026-09-17
 * @note    需手动管理节点内存
 */

3.2 函数注释

在函数定义前使用 Doxygen 风格注释，说明功能、参数和返回值。

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

3.3 行内注释

• 用于解释复杂逻辑、算法步骤或魔法数字（Magic Numbers）。

• 单行注释，如 i++; // i 加 1。

4. 函数设计与模块化 (Function Design)

4.1 单一职责原则

• 每个函数只做一件事。

• ‌长度限制‌：建议函数体不超过 ‌50 行‌。如果过长，请拆分为子函数。

4.2 参数与返回值

• ‌参数数量‌：建议不超过 5 个。如果过多，考虑封装成结构体传递。

• ‌返回值检查‌：调用可能失败的函数（如 malloc, fopen, read）时，‌必须‌检查返回值。

FILE *fp = fopen("data.txt", "r");
if (fp == NULL) {
    perror("Failed to open file");
    return -1;
}

4.3 头文件保护

所有 .h 文件必须使用Include Guards防止重复包含。

#ifndef MY_MODULE_H
#define MY_MODULE_H

// 内容...

#endif /* MY_MODULE_H */

5. 内存管理 (Memory Management)

C 语言没有垃圾回收，内存安全至关重要。

5.1 动态内存分配

• ‌检查空指针‌：malloc/calloc 返回后必须检查是否为 NULL。

• ‌成对出现‌：malloc 和 free 应在同一逻辑层级或模块中管理。

• 
  

‌释放后置空‌：释放指针后立即将其赋值为 NULL，防止悬空指针（Dangling Pointer）

int *buf = (int *)malloc(size * sizeof(int));
if (buf == NULL) {
    return NULL;
}

// 使用 buf...

free(buf);
buf = NULL; // 重要！

5.2 栈内存

• 避免在函数中返回局部变量的地址。

• 大型数组或结构体建议在堆上分配或通过指针传递，避免栈溢出。

6. 综合代码示例

以下是一个符合上述规范的完整示例：

 
/**
 * @file    calculator.c
 * @brief   简单的计算器模块示例
 */

#include <stdio.h>
#include <stdlib.h>

/* 宏定义：全大写，下划线分隔 */
#define MAX_INPUT_LENGTH 100
#define DEFAULT_PRECISION 2

/* 全局变量：加 g_ 前缀，尽量少用 */
static int g_calculation_count = 0;

/**
 * @brief 安全地读取用户输入的双精度浮点数
 * @param prompt 提示信息
 * @return 读取到的数值，失败返回 0.0 并打印错误
 */
double get_user_input(const char *prompt)
{
    double value = 0.0;
    
    printf("%s", prompt);
    if (scanf("%lf", &value) != 1) {
        fprintf(stderr, "Error: Invalid input.\n");
        /* 清除输入缓冲区 */
        while (getchar() != '\n'); 
        return 0.0;
    }
    
    return value;
}

/**
 * @brief 计算两个数的平均值
 * @param a 第一个数
 * @param b 第二个数
 * @return 平均值
 */
double calculate_average(double a, double b)
{
    g_calculation_count++;
    return (a + b) / 2.0;
}

int main(void)
{
    double num1 = 0.0;
    double num2 = 0.0;
    double average = 0.0;

    /* 获取输入 */
    num1 = get_user_input("Enter first number: ");
    num2 = get_user_input("Enter second number: ");

    /* 计算 */
    average = calculate_average(num1, num2);

    /* 输出结果 */
    printf("Average of %.2f and %.2f is %.2f\n", num1, num2, average);
    printf("Total calculations performed: %d\n", g_calculation_count);

    return 0;
}

总结建议

一致性高于一切‌：无论选择哪种风格（如 K&R 还是 Allman），团队内部必须保持一致。
利用工具‌：使用 clang-format 或 astyle 等工具 自动格式化代码，减少人工争议。
编译器警告‌：编译时开启最高警告级别（如 GCC 的 -Wall -Wextra），并将警告视为错误处理。