55、【OS】【Nuttx】编码规范解读（三）

背景

接之前 blog
53、【OS】【Nuttx】编码规范解读（一）
54、【OS】【Nuttx】编码规范解读（二）
分析了行宽格式，注释要求等，下面继续来分析

Nuttx 编码规范

注释

右侧长注释

• 语句，数据定义右侧的注释必须简短，并且不应超过规定限制 78 个字符
• 如果需要更长的注释，要把注释放在语句或定义的上方，而不是右侧

拆分长注释到右侧

可以接受将较长的注释拆分放到语句或数据定义的右侧，但不鼓励，需遵循以下规则

• 多行右置注释的第一行以注释起始定界符 (/*) 开头
• 后续每行都以一个星号 (*) 开头，并且这些星号应在同一列对齐
• 最后一行的注释结束定界符 (*/) 应与星号在同一行，并且星号也应与其他行中的星号对齐在同一列（这是唯一和上方注释不同的地方，上方注释的结束定界符需单独成行）
  举例如下

C风格注释

• C99/C11/C++风格的注释（即使用//开头的单行注释）不应在NuttX项目中使用
• NuttX项目遵循C89标准，所有不在架构特定目录下（就是为了新特性开的目录）的代码必须兼容C89标准，以保持代码的一致性和兼容性

临时禁用

• 不要使用C或C++风格的注释来禁用大段代码：通常，开发人员可能会使用 /* */（C风格注释）或 //（C++风格注释）来注释掉一大段代码以暂时不编译这部分代码，这种方法在嵌套注释的情况下容易出错
• 建议使用 #if 0 来代替临时禁用代码：推荐使用预处理指令 #if 0 和对应的 #endif 来包围想要禁用的代码块，这样可以避免由于注释嵌套引起的潜在问题，并且更清晰明了
• 在 #if 0 前添加解释性注释：使用#if 0时，要在前面加上注释，说明为啥这些代码块被禁用了，以帮助其他开发人员理解原因，增加代码的可维护性和可读性

举例如下

花括号

Nuttx 项目中花括号的使用和 GNU 编码规范 类似，但也有点细小的差别

• 单独成行：左右花括号 {} 要独占一行，除了空白字符外不要包含其他任何内容
• 不要将注释放到花括号所在行上
• 在 Nuttx 规范中，由左花括号开始，接着一系列语句，最后以右花括号结束的代码块被称为复合语句
• 当存在嵌套的复合语句导致连续出现多个右花括号时，每个右花括号必须独占一行，并且需要适当缩进，以匹配对应的左花括号

规则要求右花括号后面要有一个空行，除了下面两种例外情况：

• 有多个连续的右花括号时，除了最后一个右花括号之外，其他的右花括号不要有空行
• 如果右花括号后面紧跟着一个break;语句，则不要留出空行

举例如下


这里花括号的写法有点奇怪，其实这是 GNU 风格。在编程中，花括号风格（Brace Style）指的是如何放置代码块的花括号 {}，不同的风格有不同的约定，常见有如下三种风格：

K&R 风格：得名于C语言的发明者 Brian Kernighan 和 Dennis Ritchie，特点如下：

• 左花括号 { 紧跟在控制语句（如 if、for、while 等）后，与之位于同一行
• 右花括号 } 单独放在控制结构结束的一行
• 函数定义时，左花括号独立成行

if (condition) {// code block
}
...
void function(...)
{// code block
}

该命名风格紧凑且不会浪费空间，推荐！

Allman 风格：以程序设计师Eric Allman的名字命名，特点如下：

• 左花括号 { 总是放在控制语句的下一行，不与控制语句在同一行
• 右花括号 } 单独放在控制结构结束的一行

if (condition)
{// code block
}

GNU 风格：在 Allman 风格的基础上，花括号需要额外多一次缩进，效果如下（截取于 GNU 编码规范 ）

此外，GNU 风格还特别推荐使用 #if 0 来注释掉大段代码而不是使用 /* */ 或 // 注释，这点在前面提过