注釋

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

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

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

◎ 全局變量要有較詳細(xì)的注釋
◎ 函數(shù)內(nèi)部注釋：函數(shù)內(nèi)部不是注釋越多越好，而是變量命名和邏輯清晰，自注釋最好，特殊情況或者需要特別注意的地方才加注釋，并且注釋要放在代碼行的上方。
◎ 基于SDK開發(fā)，在基線工程上改動代碼，不允許刪除源代碼，修改代碼必須增加注釋，必須使用關(guān)鍵字“XX_CODE”標(biāo)注修改原因，方便后續(xù)打補(bǔ)丁，范例如下：

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

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

排版與格式

◎ 程序塊釆用縮進(jìn)風(fēng)格編寫，每級縮進(jìn)為4個空格。
◎ 相對獨立的程序塊之間、變量說明之后必須加空行。
◎ 多個短語句不允許寫在同一行內(nèi)，長語句不能拆分需要分行寫。
◎ if、for、do、while、case、switch、default等語句獨占一行，｛換行且獨占一行。
◎ 賦值語句不要寫在if等語句中，或者作為函數(shù)的參數(shù)使用。
◎ 邏輯表達(dá)式每個子項都使用（）。
◎ 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語句必須有default分支。
◎ 在兩個以上的關(guān)鍵字、變量、常量進(jìn)行對等操作時，它們之間的操作符之前、之后或者前后要加空格；進(jìn)行非對等操作時（如->），后面不應(yīng)加空格。
◎ 文件編寫完成后，統(tǒng)一使用Astyle自動格式化工具整理一遍再提交到版本庫。

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

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