编码规范¶
Nexus 遵循严格的编码规范以确保质量和安全。
C 标准¶
源代码使用 C11
测试使用 C++17
代码格式化¶
项目使用 clang-format 进行自动代码格式化。提交代码前请运行 clang-format。
See also: .kiro/steering/comment-standards.md for detailed comment guidelines.
缩进¶
使用 4 个空格缩进（不使用制表符）
switch 语句中的 case 标签需要缩进
预处理指令不缩进
行长度¶
最大行长度：80 个字符
在适当位置断开长行
大括号¶
Use attached braces (K&R style):
if (condition) {
/* code */
} else {
/* code */
}
void function(void) {
/* code */
}
空格¶
控制关键字后加空格：
if (、for (、while (函数名后不加空格：
func()类型转换后不加空格：
(int)value行尾注释前加两个空格
二元运算符两侧加空格：
a + b、x = y
指针对齐¶
Pointers align to the left (with the type):
int* ptr; /* Correct */
char* str; /* Correct */
空行¶
最多一个连续空行
使用空行分隔逻辑段落
命名约定¶
函数：
module_action_object()``（例如 ``hal_gpio_init()）类型：
module_type_t``（例如 ``hal_status_t）宏：
MODULE_MACRO_NAME``（例如 ``HAL_OK）常量：
MODULE_CONSTANT``（例如 ``HAL_GPIO_PORT_MAX）静态变量：
s_variable_name前缀全局变量：
g_variable_name前缀（尽量避免使用）
文档¶
所有公共 API 必须有 Doxygen 注释。本项目使用 \ 风格的 Doxygen 标签（不使用 @ 风格）。
标签对齐¶
All Doxygen tags must be aligned to column 20 (17 spaces after *).
This ensures consistent formatting across the codebase:
/**
* \brief Brief description starts at column 20
* \param[in] param: Parameter description
* \param[out] result: Output parameter description
* \return Return value description
*/
文件头格式¶
Every source file must have a file header comment.
Header files (.h) - Minimal format:
/**
* \file filename.h
* \brief Brief description of the file
* \author Nexus Team
*/
Source files (.c) - Full format with version and copyright:
/**
* \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)¶
Header files contain full API documentation including parameters and return values:
/**
* \brief Create a mutex
* \param[out] handle: Pointer to store mutex handle
* \return OSAL_OK on success, error code otherwise
*/
osal_status_t osal_mutex_create(osal_mutex_handle_t* handle);
源文件 (.c)¶
Source files should NOT duplicate \param and \return documentation
from headers. Use only \brief, \details, and \note:
/**
* \brief Create a mutex
* \details Allocates and initializes a new mutex object.
* The mutex is created in unlocked state.
* \note Thread-safe function.
*/
osal_status_t osal_mutex_create(osal_mutex_handle_t* handle) {
/* Implementation */
}
段落注释¶
Use section comments to organize code into logical blocks. The separator line
must be exactly 77 characters (/* + 75 characters + */):
/*---------------------------------------------------------------------------*/
/* Section Name */
/*---------------------------------------------------------------------------*/
Important: Do NOT use /*===...===*/ style separators. Always use
/*---...---*/ for consistency.
行内注释¶
Use /* comment */ style for inline comments, not //:
int value = 0; /* Initialize to zero */
Macro Comments¶
Use Doxygen block comments or inline comments for macros:
/**
* \brief Maximum buffer size
*/
#define MAX_BUFFER_SIZE 256
/* Or use inline style */
#define MAX_BUFFER_SIZE 256 /**< Maximum buffer size */
Static Functions¶
Static functions use simplified comments with only \brief:
/**
* \brief Internal helper function description
*/
static void internal_helper(void) {
/* Implementation */
}
Prohibited Practices¶
The following practices are NOT allowed:
Using
@style Doxygen tags (use\instead)Using
//single-line comments (use/* */instead)Using
/*===...===*/section separators (use/*---...---*/instead)Duplicating
\paramand\returnin source files (only in headers)
MISRA C¶
代码应符合 MISRA C:2012 准则。