高内聚工具函数的核心是职责极窄、边界极清、复用极强；函数声明即接口契约，需形参精简、返回值明确、命名动宾、杜绝全局依赖，并配套前缀规范、禁用void*与可变参数。
直接说重点：高内聚的底层工具库方法，核心不是“写得多”，而是“职责极窄、边界极清、复用极强”。函数声明是第一步，也是定调这三要素的锚点。
声明即契约：用函数签名锁定内聚边界
函数声明不是占位符，而是对外承诺的接口契约。一个真正高内聚的工具函数，其声明必须一眼看出它只干一件事，且这件事不依赖外部状态。
- 返回值类型明确——不返回 void 除非纯粹副作用（如日志打印），否则必有语义清晰的返回值，比如 int parsePort(const char* str) 而非 void parsePort(const char* str, int* out)
- 形参精简且只传必要数据——拒绝“万能参数包”，例如用 bool isValidEmail(const char* email, size_t len)，而不是传入整个配置结构体
- 函数名直指本质动作+对象——采用动宾结构，如 strTrimLeft、bufCopySafe、timeMsSinceBoot，不加模糊前缀（如 util_、helper_）
避开全局变量污染，靠声明隔离作用域
底层工具库最怕隐式依赖。声明阶段就要切断对全局变量的幻想：
- 所有输入必须显式通过参数传入，包括配置、上下文、缓冲区——哪怕多写两个参数，也比在函数里读 g_config.timeout_ms 更内聚
- 若真需共享状态（极少数情况，如硬件寄存器映射地址），用 static const 在 .c 文件内定义，不在头文件中暴露，更不靠 extern 拉全局变量
- C语言中，函数声明放在头文件（.h），但绝不声明任何全局变量；所有实现细节、静态数据、临时缓冲都藏在 .c 文件里
声明先行，强制驱动测试与文档同步
先写声明，再写实现，这个顺序能天然倒逼高内聚设计：
- 写声明时卡住：发现要传5个参数？说明职责过宽，该拆成2个函数
- 写声明时犹豫：返回值该用 int 还是 enum？说明语义不清晰，得先定义错误码枚举（如 typedef enum { OK, ERR_NULL_PTR, ERR_OVERFLOW } status_t;）
- 每个函数声明上方，强制写 1 行注释说明用途 + 1 行示例调用，例如：
// Parses IPv4 address string (e.g., "192.168.1.1") into uint32_t network byte order
// uint32_t ip = inetParseV4("10.0.0.1");
配套声明习惯：让内聚可验证、可演进
仅写对声明还不够，需搭配工程习惯固化内聚性：
- 头文件中所有工具函数声明统一加前缀，如 os_（操作系统层）、hal_（硬件抽象层）、str_（字符串工具），前缀即领域边界
- 禁用可变参数函数（printf-style）做通用工具——它们天然低内聚；如需格式化，提供专用函数如 strFormatHex(uint8_t*, size_t, uint32_t)
- 声明中避免使用 void*，除非是泛型容器底层（如链表操作）；优先用具体类型或带 tag 的结构体，例如 typedef struct { uint8_t data[32]; size_t len; } blob_t;，然后声明 bool blobEqual(const blob_t*, const blob_t*)
