c代碼Doxygen註釋規範

c代碼Doxygen註釋規範

---

前言：良好得註釋風格利於後期維護和團隊協作開發，使得代碼邏輯清晰，意圖明瞭。Doxygen是一種能自動提取代碼內註釋生成版主文檔的開源軟件，它是跨平臺的。非開源項目也許並不需要有這樣一份幫助文檔，但Doxygen的註釋規範也不失爲一種好的風格，可以推廣遵守。

Doxygen註釋規範模板

文件註釋模板

/**
  * @file 文件名（*.h/*.c）
  * @brief 該模塊功能的簡介。
  * @details 使用該模塊有哪些細節注意等。
  * @author 創建該文件的人名。
  * @data 該文件的創建日期（2020-03-10）。
  * @version 文件當前的版本號（V1.0.0）。
  * @copyright 版權所屬公司。
  */

函數註釋模板

/**
  * @fn 函數名
  * @brief 簡述函數功能。
  * @details 提示一些注意事項或必要的技術細節。
  * @param[in] 參數名 參數註解
  * @param[out] 參數名 參數註解
  * @param[in, out] 參數名 參數註解
  * @return None （宏函數無返回值）
  * @retval 對返回值的說明
  * @see 扇入：調用了該函數的上級函數（扇入高表示該函數複用性好）
  * @see 扇出：該函數裏調用了哪些下級函數（扇出高表示該函數複雜度高）
  * @note 註解。
  * @attention 注意事項。
  * @par example:
  * @code
  //代碼示例
  * @endcode
  */

宏函數註釋模板

/**
  * @def 宏函數名
  * @brief 簡述函數功能。
  * @details 提示一些注意事項或必要的技術細節。
  * @param[in] 參數名 參數註解
  * @param[out] 參數名 參數註解
  * @param[in, out] 參數名 參數註解
  * @return None （宏函數無返回值）
  * @see 扇入：調用了該函數的上級函數（扇入高表示該函數複用性好）
  * @see 扇出：該函數裏調用了哪些下級函數（扇出高表示該函數複雜度高）
  * @note 註解。
  * @attention 注意事項。
  * @par example:
  * @code
  //代碼示例
  * @endcode
  */

變量/宏定義註釋模板

#define MAX                //!< 最大值
Byte g_byMax = 0;          //!< 全局變量，最大值

枚舉註釋模板

/**
  * @enum 枚舉名
  * @brief 簡介枚舉用途。
  * @details 提示一些注意事項或必要的技術細節。
  * @note 註解。
  * @attention 注意事項。
  */

個人建議將枚舉值也定義爲宏

聯合註釋模板

/**
  * @union 聯合名
  * @brief 簡介聯合用途。
  * @details 提示一些注意事項或必要的技術細節。
  * @note 註解。
  * @attention 注意事項。
  */

個人建議將聯合按8Bit進行位劃分

結構體註釋模板

/**
  * @struct 結構體名
  * @brief 簡介結構體用途。
  * @details 提示一些注意事項或必要的技術細節。
  * @note 註解。
  * @attention 注意事項。
  */

遵循以上註釋風格將會使你的代碼更加規範，可讀性增強。對於團隊開發來說有一個統一的規範標準也使得協作變得簡單。