代码规范

Nexus 遵循严格的代码规范，以保障质量与安全。

C 语言标准

  • 源码采用 C11

  • 生产代码及维护范围内的 C 合同夹具采用 C11

  • 主机 GoogleTest/GoogleMock 及外部 ABI 消费验证采用 C++17；测试框架和其 C++ 运行时均不进入固件

代码格式

项目使用 clang-format 自动格式化代码。提交代码前运行 clang-format。

详细注释规则另见 .kiro/steering/comment-standards.md。

缩进

  • 使用 4 个空格缩进，不使用制表符

  • switch 语句中的 case 标签需要缩进

  • 预处理指令不缩进

行长度

  • 每行最长 80 个字符

  • 在适当位置拆分长行

花括号

使用附着式花括号（K&R 风格）:

if (condition) {
    /* code */
} else {
    /* code */
}

void function(void) {
    /* code */
}

空格

  • 控制关键字后加空格：if (、for (、while (

  • 函数名后不加空格：func()

  • 类型转换后不加空格：(int)value

  • 行尾注释之前保留两个空格

  • 二元运算符两侧加空格：a + b、x = y

指针对齐

指针星号靠左，与类型连接:

int* ptr;           /* Correct */
char* str;          /* Correct */

空行

  • 最多保留一个连续空行

  • 使用空行分隔逻辑段落

命名约定

  • 函数：module_action_object()，例如 nx_gpio_port_write()

  • 类型：module_type_t，例如 nx_result_t

  • 宏：MODULE_MACRO_NAME，例如 NX_SUCCESS

  • 常量：MODULE_CONSTANT，例如 NEXUS_UART0_SELECTED

  • 静态变量：使用 s_variable_name 前缀

  • 全局变量：使用 g_variable_name 前缀，尽可能避免全局变量

文档注释

全部公共 API 必须带 Doxygen 注释。本项目使用 \\ 风格 Doxygen 标签，不使用 @ 风格。

标签对齐

按下方示例对齐每个 Doxygen 标签后的说明。不计外围代码缩进，说明从第 21 列开始：注释起始星号之后，标签及其填充共占 17 个字符:

/**
 * \brief           Brief description starts at column 21
 * \param[in]       param: Parameter description
 * \param[out]      result: Output parameter description
 * \return          Return value description
 */

文件头格式

每个源文件必须包含文件头注释。

头文件 (.h)：最小格式:

/**
 * \file            filename.h
 * \brief           Brief description of the file
 * \author          Nexus Team
 */

源文件 (.c)：包含版本与版权的完整格式:

/**
 * \file            filename.c
 * \brief           Brief description of the file
 * \author          Nexus Team
 * \version         1.0.0
 * \date            2026-01-12
 *
 * \copyright       Copyright (c) 2026 Nexus Team
 *
 * \details         Detailed description of the file contents
 *                  and purpose. Can span multiple lines.
 */

头文件 (.h)

头文件包含完整 API 文档，包括参数与返回值:

/**
 * \brief           Prepare an exclusively owned reusable request.
 * \param[in,out]   request: Quiescent caller storage.
 * \param[in]       deadline: Absolute monotonic deadline.
 * \return          Success or STATE while an earlier borrow remains.
 */
nx_result_t nx_request_prepare(nx_request_t* request, nx_time_us_t deadline);

源文件 (.c)

源文件定义应解释硬件顺序与不变量，不重复头文件中的 \param 或 \return。按需要使用 \brief、\details 与 \note:

/** \brief           Restore the saved incoming interrupt mask. */
void nx_arch_irq_restore(nx_arch_irq_state_t state) {
    /* Implementation */
}

章节注释

使用章节注释将代码分为逻辑块。分隔线必须准确包含 79 个字符，即 /* + 75 个字符 + */，保持既有模板:

/*---------------------------------------------------------------------------*/
/* Section Name                                                              */
/*---------------------------------------------------------------------------*/

要求：不得使用 /*===...===*/ 分隔线。统一使用 /*---...---*/。

行内注释

行内注释使用 /* comment */ 风格，不使用 //:

int value = 0;  /* Initialize to zero */

宏注释

宏使用 Doxygen 块注释或行内注释:

/**
 * \brief           Maximum buffer size
 */
#define MAX_BUFFER_SIZE 256

/* Or use inline style */
#define MAX_BUFFER_SIZE 256  /**< Maximum buffer size */

静态函数

静态函数使用仅包含 \brief 的简化注释:

/**
 * \brief           Internal helper function description
 */
static void internal_helper(void) {
    /* Implementation */
}

禁止事项

禁止以下做法：

  • 使用 @ 风格 Doxygen 标签；必须改用 \\

  • 使用 // 单行注释；必须改用 /* */

  • 使用 /*===...===*/ 章节分隔线；必须改用 /*---...---*/

  • 在源文件重复 \param 和 \return；它们只能位于头文件

所有权与证据

公共声明必须说明上下文、截止时间、保留的存储及失败状态。解释为何必须执行 volatile 读取、顺序屏障或排空。SETTLED 的发布是提供者对请求的最后一次访问。取消绝不允许在完成并排空或证明受控恢复之前回收借用缓冲区。

修改的文件必须通过全文件格式及机械注释检查。使用 python scripts/setup/install_dev_tools.py 安装本地 Git 钩子。commit 与 CI 门禁共享 scripts/ci/style_gate.py；绕过钩子不构成验证结果。实际编译警告／分析器与行为证据独立于风格检查。

选定分析器检查不建立 MISRA 认证或工业功能安全资格。