如何规范嵌入式C编码注释以及排版与格式

注释

◎ 注释应放在其代码上方相邻位置或右方，不可放在下面。
◎ 注释的内容要清楚明了，防止注释二义性。
◎ 修改代码时同步更新注释，保证注释与代码的一致性。
◎ 函数声明处注释描述函数功能、性能及用法，提供参考范本如下：

/**
 * @brief    函数功能
 * @params 
 * @return
 * @par history
 *   xx create  @2023-xx-xx
 */

微信公众号【嵌入式系统】提示，注释格式可以参考Doxygen标准。

◎ 全局变量要有较详细的注释
◎ 函数内部注释：函数内部不是注释越多越好，而是变量命名和逻辑清晰，自注释最好，特殊情况或者需要特别注意的地方才加注释，并且注释要放在代码行的上方。
◎ 基于SDK开发，在基线工程上改动代码，不允许删除源代码，修改代码必须增加注释，必须使用关键字“XX_CODE”标注修改原因，方便后续打补丁，范例如下：

/**** XX_CODE begin ****/
/*修改原因，作者，时间*/
< 代码块 >
/**** XX_CODE end ****/

对于非c源码的文件，在这个注释格式的基础上，每行添加对应的注释符号。
◎ 修改与外设驱动、通信协议、系统底层等相关的代码，具有特殊隐含限制的代码，必须提交详细的修改原因，便于后续版本回溯查找原因。
◎ 复杂且相对独立的功能，单独使用markdown文档说明开发方案、实现技术、应用场景、使用限制等，随代码提交。

排版与格式

◎ 程序块釆用缩进风格编写，每级缩进为4个空格。
◎ 相对独立的程序块之间、变量说明之后必须加空行。
◎ 多个短语句不允许写在同一行内，长语句不能拆分需要分行写。
◎ if、for、do、while、case、switch、default等语句独占一行，｛换行且独占一行。
◎ 赋值语句不要写在if等语句中，或者作为函数的参数使用。
◎ 逻辑表达式每个子项都使用（）。
◎ if与else if/else必须以’{}’分隔，且 ‘{’与‘}’各占一行，if-else分3层以上必须以else子句结束，即使操作为空，并增加注释://do nothing

if(var==xx)
{
  …
}
else if (var==yy)
{
  …
}
else if (var==zz)
{
  …
}
else
{
  //do nothing
}

◎ switch语句必须有default分支。
◎ 在两个以上的关键字、变量、常量进行对等操作时，它们之间的操作符之前、之后或者前后要加空格；进行非对等操作时（如->），后面不应加空格。
◎ 文件编写完成后，统一使用Astyle自动格式化工具整理一遍再提交到版本库。

astyle.exe --style=allman -S -U -t -n -K -p -s4 -j -q -Y -xW -xV

微信公众号【 嵌入式系统 】提示，可以参考《代码的保养》；排版格式很多，一个团队最重要的是统一风格。