函数、作用域与头文件：C 程序如何拆成多个文件

C 程序变大后，不能把所有代码都写进 main。 函数负责拆分动作，作用域负责限制名字可见范围，头文件负责暴露跨文件契约。 这些概念看似基础，实际连接到链接器、ABI、封装和资源释放。 如果函数边界设计不好，后面多文件工程会变成难以审计的全局泥团。

函数是什么

函数是一段有名字的代码。 它可以接收参数，可以返回结果。

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

这段函数：

• 名字是 add。
• 返回类型是 int。
• 参数是两个 int。
• 函数体在 {} 中。

调用：

int result = add(1, 2);

函数像一个明确入口。 调用方只需要知道输入、输出和副作用。

函数声明和定义

声明告诉编译器函数存在。 定义提供函数体。

int add(int a, int b);       // 声明

int add(int a, int b) {      // 定义
  return a + b;
}

声明可以出现多次。 定义通常只能有一个。 如果只声明不定义，编译可能通过，链接会失败。

参数是按值传递

C 的函数参数默认按值传递。 函数收到的是实参值的副本。

void set_zero(int x) {
  x = 0;
}

调用后外部变量不会变。

int n = 5;
set_zero(n);
// n 仍然是 5

要修改外部对象，需要传指针。

void set_zero(int* x) {
  *x = 0;
}

这就是指针和函数边界第一次相遇。

返回值表达结果

函数可以返回值。 也可以用 void 表示不返回值。

int parse(const char* text);
void log_message(const char* text);

C 里常用返回码表达成功或失败。

int open_config(const char* path) {
  if (path == NULL) {
    return -1;
  }
  return 0;
}

返回码必须被调用方检查。 忽略错误码是 C 工程中非常常见的风险。

作用域限制名字可见性

局部变量只在块内可见。

void f(void) {
  int x = 1;
  {
    int y = 2;
  }
  // y 在这里不可见
}

作用域像房间门。 名字只在房间内有效。 合理缩小作用域，可以减少误用和并发共享风险。

文件作用域和全局变量

在函数外声明的名字具有文件作用域。

int global_count = 0;

全局变量容易让多个函数隐式耦合。 如果它可变，还会带来测试隔离和并发问题。 入门阶段可以知道它存在，但不要把它当作默认设计。

static 限制文件内可见

文件作用域的 static 让名字只在当前源文件可见。

static int helper(int x) {
  return x * 2;
}

这是 C 的封装手段。 如果一个函数不需要被其他源文件调用，就应该声明为 static。 这样链接器不会把它暴露成外部符号。

头文件放声明

头文件通常放公共声明，不放普通函数定义。

// math_utils.h
#ifndef MATH_UTILS_H
#define MATH_UTILS_H

int add(int a, int b);

#endif

源文件提供定义：

// math_utils.c
#include "math_utils.h"

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

调用方包含头文件：

#include "math_utils.h"

include guard 防止重复包含

头文件可能被多个文件间接包含。 include guard 防止重复声明引发问题。

#ifndef CONFIG_H
#define CONFIG_H

typedef struct Config Config;

#endif

也可以用 #pragma once。 它简单，但不是 ISO C 标准的一部分。 工程中根据项目约定选择。

头文件是契约，不是垃圾桶

不要把所有声明都塞进一个巨大头文件。 头文件越大：

• 编译越慢。
• 依赖越乱。
• 改动影响面越大。
• 宏污染越严重。
• ABI 边界越不清楚。

头文件应该暴露最小必要接口。 内部函数留在 .c 文件中并使用 static。

多文件编译

假设有三个文件：

src/
├── main.c
├── math_utils.c
└── math_utils.h

编译：

clang -std=c23 -Wall -Wextra -c src/math_utils.c -o math_utils.o
clang -std=c23 -Wall -Wextra -c src/main.c -o main.o
clang main.o math_utils.o -o app

第一步分别生成目标文件。 第二步链接。 这就是多文件工程的基本模型。

函数边界要表达所有权

如果函数返回指针，必须说清谁释放。

char* read_file(const char* path);
void free_buffer(char* buffer);

调用方看到这组 API，就知道 read_file 返回拥有者指针，必须用 free_buffer 释放。 如果只写 char* read_file(...) 而没有释放协议，资源泄漏迟早发生。

不要滥用宏替代函数

宏在预处理阶段做文本替换。

#define SQUARE(x) ((x) * (x))

如果传入有副作用的表达式：

int y = SQUARE(i++);

i++ 会被展开两次。 这类宏非常危险。 能用函数就不要用宏。 需要宏时要清楚它是文本替换，不是函数调用。

递归函数

函数可以调用自己。

int factorial(int n) {
  if (n <= 1) {
    return 1;
  }
  return n * factorial(n - 1);
}

递归必须有终止条件。 否则会耗尽栈空间。 生产代码里递归深度要受控，尤其是处理用户输入的树或图。

函数设计原则

一个函数应该做一件清晰的事。 入门阶段可以遵守：

• 参数不要太多。
• 返回值要表达成功失败。
• 不偷偷修改全局状态。
• 错误路径要释放资源。
• 名字表达动作。
• 函数体保持短小。

这不是形式主义。 函数越小，边界越容易测试和审计。

工程风险

函数和头文件常见风险：

• 只声明不定义导致链接错误。
• 多个源文件重复定义全局变量。
• 头文件放普通函数定义导致重复定义。
• 公共头文件暴露内部结构，破坏封装。
• 函数返回局部变量地址。
• 返回资源但没有释放协议。
• 全局变量造成并发数据竞争。
• 宏参数重复求值。

这些问题会在多文件工程里被放大。

小结

函数把程序拆成可理解的动作。 作用域限制名字的影响范围。 头文件定义跨文件契约。 C 的模块化不是靠复杂框架，而是靠清晰的声明、定义、链接和可见性规则。 从入门阶段就把函数边界写清楚，后面的指针、内存和工程化才有稳定地基。