// 错误：防护符与文件路径无关，易冲突
#ifndef UTILS_H
#define UTILS_H
// 正确：基于完整路径（假设文件在project/utils/io.h）
#ifndef PROJECT_UTILS_IO_H
#define PROJECT_UTILS_IO_H
#endif

// utils.h（未包含foo.h）
struct Foo;  // 前向声明
void process_foo(struct Foo* foo);  // 风险：若Foo实际定义与声明不一致，编译不报错！
// 正确做法：直接包含foo.h
#include "foo.h"
void process_foo(struct Foo* foo);

// 反例：变量作用域过大，且未初始化
int flag;  // 全局作用域，可能被意外修改
void func() {
    flag = 0;  // 第一步：赋值
    if (condition) {
        flag = 1;  // 第二步：修改
    }
}
// 正确做法：在需要处声明并初始化
void func() {
    if (condition) {
        int flag = 1;  // 作用域仅限if块，初始化即赋值
    } else {
        int flag = 0;  // 同样作用域明确
    }
}

// 反例：每次循环都声明大数组（栈空间可能不足）
void process() {
    for (int i = 0; i < 1000; i++) {
        int big_array[1024];  // 每次循环重新分配栈空间
        // ...
    }
}
// 正确做法：在循环外声明，或使用动态分配（需注意释放）
void process() {
    int big_array[1024];  // 仅声明一次
    for (int i = 0; i < 1000; i++) {
        // 复用数组
    }
}

// 反例：一个函数处理输入、计算、输出，逻辑混乱
void handle_user() {
    read_input();       // 输入
    validate_input();   // 校验
    calculate_result(); // 计算
    print_result();     // 输出
    save_to_file();     // 存储
}

// 反例：输入输出参数混杂，调用时易混淆
void update_user(char name, int age, const char* new_name, int new_age) {
    strcpy(name, new_name);  // 输入参数name被修改（实际是输出）
    *age = new_age;          // 输出参数age
}
// 正确做法：输入参数在前，输出参数在后
void update_user(const char new_name, int new_age, char name, int* age) {
    strcpy(name, new_name);  // 输入：new_name；输出：name
    *age = new_age;          // 输入：new_age；输出：age
}

// 反例：VLA可能导致栈溢出
void process(int n) {
    int arr[n];  // 危险！n过大时栈溢出
}
// 正确做法：动态分配（需手动释放）
void process(int n) {
    int arr = malloc(n*sizeof(int));  // 堆分配，更安全
    // ...
    free(arr);  // 务必释放！
}

// 反例：未使用const，可能意外修改只读数据
char* get_config() {
    return "default_config";  // 返回字符串字面量（只读）
}
// 正确做法：用const修饰指针，防止意外修改
const char* get_config() {
    return "default_config";  // 明确告知调用者：不可修改！
}

// 危险宏：参数可能被多次求值（如i++）
#define MAX(a,b) ((a)>(b)?(a):(b))
int i = 1;
int max_val = MAX(i++, 2);  // i会被递增两次（i=3），而非预期的一次（i=2）
// 替代方案：内联函数
static inline int max(int a, int b) {
    return a > b ? a : b;
}
int max_val = max(i++, 2);  // i仅递增一次（i=2）

// 结构体类型名
typedef struct {
    char name[32];
    int age;
} UserInfo;  // 大驼峰，明确是类型
// 枚举类型名
typedef enum {
    STATE_IDLE,
    STATE_RUNNING
} DeviceState;  // 大驼峰，表示枚举类型

void process_user(UserInfo* user) {
    int user_age = user->age;  // 变量名：user_age（描述用途）
    char* input_buffer = malloc(1024);  // 参数名：input_buffer（描述用途）
}

/*
user_utils.h - 用户信息处理工具集
* 功能：提供用户信息的创建、校验、打印接口，依赖标准库stdio.h和string.h。
* 与其他模块关系：依赖network.h中的日志接口，被main.c调用。
*/

// 头文件声明（功能）
/*
计算两个整数的和
@param a 第一个整数（输入）
@param b 第二个整数（输入）
@return 两数之和（输出）
*/
int add_numbers(int a, int b);
// 源文件定义（实现）
int add_numbers(int a, int b) {
    // 边界条件：处理整数溢出（示例）
    if ((b > 0 && a > INT_MAX - b) || (b < 0 && a < INT_MIN - b)) {
        fprintf(stderr, "Error: Integer overflow!\n");
        exit(EXIT_FAILURE);
    }
    return a + b;
}