如何規(guī)范嵌入式C編碼注釋以及排版與格式

注釋

◎ 注釋?xiě)?yīng)放在其代碼上方相鄰位置或右方，不可放在下面。
◎ 注釋的內(nèi)容要清楚明了，防止注釋二義性。
◎ 修改代碼時(shí)同步更新注釋?zhuān)ＷC注釋與代碼的一致性。
◎ 函數(shù)聲明處注釋描述函數(shù)功能、性能及用法，提供參考范本如下：

/**
 * @brief    函數(shù)功能
 * @params 
 * @return
 * @par history
 *   xx create  @2023-xx-xx
 */

微信公眾號(hào)【嵌入式系統(tǒng)】提示，注釋格式可以參考Doxygen標(biāo)準(zhǔn)。

◎ 全局變量要有較詳細(xì)的注釋
◎ 函數(shù)內(nèi)部注釋?zhuān)汉瘮?shù)內(nèi)部不是注釋越多越好，而是變量命名和邏輯清晰，自注釋最好，特殊情況或者需要特別注意的地方才加注釋?zhuān)⑶易⑨屢旁诖a行的上方。
◎ 基于SDK開(kāi)發(fā)，在基線(xiàn)工程上改動(dòng)代碼，不允許刪除源代碼，修改代碼必須增加注釋?zhuān)仨毷褂藐P(guān)鍵字“XX_CODE”標(biāo)注修改原因，方便后續(xù)打補(bǔ)丁，范例如下：

/**** XX_CODE begin ****/
/*修改原因，作者，時(shí)間*/
< 代碼塊 >
/**** XX_CODE end ****/

對(duì)于非c源碼的文件，在這個(gè)注釋格式的基礎(chǔ)上，每行添加對(duì)應(yīng)的注釋符號(hào)。
◎ 修改與外設(shè)驅(qū)動(dòng)、通信協(xié)議、系統(tǒng)底層等相關(guān)的代碼，具有特殊隱含限制的代碼，必須提交詳細(xì)的修改原因，便于后續(xù)版本回溯查找原因。
◎ 復(fù)雜且相對(duì)獨(dú)立的功能，單獨(dú)使用markdown文檔說(shuō)明開(kāi)發(fā)方案、實(shí)現(xiàn)技術(shù)、應(yīng)用場(chǎng)景、使用限制等，隨代碼提交。

排版與格式

◎ 程序塊釆用縮進(jìn)風(fēng)格編寫(xiě)，每級(jí)縮進(jìn)為4個(gè)空格。
◎ 相對(duì)獨(dú)立的程序塊之間、變量說(shuō)明之后必須加空行。
◎ 多個(gè)短語(yǔ)句不允許寫(xiě)在同一行內(nèi)，長(zhǎng)語(yǔ)句不能拆分需要分行寫(xiě)。
◎ if、for、do、while、case、switch、default等語(yǔ)句獨(dú)占一行，｛換行且獨(dú)占一行。
◎ 賦值語(yǔ)句不要寫(xiě)在if等語(yǔ)句中，或者作為函數(shù)的參數(shù)使用。
◎ 邏輯表達(dá)式每個(gè)子項(xiàng)都使用（）。
◎ if與else if/else必須以’{}’分隔，且 ‘{’與‘}’各占一行，if-else分3層以上必須以else子句結(jié)束，即使操作為空，并增加注釋://do nothing

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

◎ switch語(yǔ)句必須有default分支。
◎ 在兩個(gè)以上的關(guān)鍵字、變量、常量進(jìn)行對(duì)等操作時(shí)，它們之間的操作符之前、之后或者前后要加空格；進(jìn)行非對(duì)等操作時(shí)（如->），后面不應(yīng)加空格。
◎ 文件編寫(xiě)完成后，統(tǒng)一使用Astyle自動(dòng)格式化工具整理一遍再提交到版本庫(kù)。

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

微信公眾號(hào)【 嵌入式系統(tǒng) 】提示，可以參考《代碼的保養(yǎng)》；排版格式很多，一個(gè)團(tuán)隊(duì)最重要的是統(tǒng)一風(fēng)格。