程式設計風格規範系列（三）：註解規範全景指南

前言

本系列第三部分建立 **註解三層體系**：檔案級、函數級、變數/行內級，並規範註解格式、內容深度與維護責任，使代碼自帶文檔屬性，大幅降低溝通成本。

一、函數頭註解：六要素標準模板

//==================================================================
// 功能：從字串 strByDelete 中刪除子字串 strToDelete
// 參數：strByDelete, strToDelete
// (入口) strByDelete: 原字串 (被刪除對象)
// (出口) strToDelete: 待刪除子字串
// 返回：找到並刪除傳回 1，否則 0 (含錯誤碼說明)
// 主要思路：循環比較法尋找匹配；未處理多重匹配情況
// 參閱：《字串演算法精解》P.45
// 調用方法：int n = DeleteSubStr(buf, "abc");
// 日期：2000/08/21 09:40 -- 2000/08/23 21:45
//==================================================================
int DeleteSubStr(char* strByDelete, const char* strToDelete);

關鍵規範

1. 入口/出口標註：參數雙向傳遞時必須雙標；單位不明確者 (角度/弧度) 必須註明。
2. 雙重放置：標頭檔宣告處 + 實作檔定義處 **同步維護** 兩份註解。
3. 思路與來源**：核心演算法邏輯、參考書目/論文/連結、個人心得/靈感來源。
4. 調用範例與陷阱：示範正確調用、警示常見誤用 (如緩衝區大小不足)。
5. 日期區間：從動筆到測試通過的完整時間跨度，利於專案追蹤。
6. 特殊標識串**：`//==================================================================` 包裹，便於工具提取/折疊。

二、變數註解：緊跟定義，說明語義而非型別

long lLineCount;   // 圖形行數
float fThreshold;  // 邊緣檢測閾值 (0.0~1.0)
int i, j;          // 迴圈索引，無需註解 (慣用慣例)

• 原則：**每個變數皆註解**，除非語義極度顯而易見 (i/j/k 迴圈變數、旗標 `bDone`)。
• 註解內容：**業務含義、取值範圍、單位、特殊約定**。

三、檔案頭註解：專案級身分證

///////////////////////////////////////////////////////////////////////
// 工程: 圖形核心庫 GeoKernel
// 作者: 張三，修改者: 李四
// 描述: 提供二維幾何基本運算 (交點、面積、布爾運算)
// 主要函數: IntersectLines, PolygonArea, BooleanOp
// 版本: v2.1.0 (2024-03-15)
// 修改: 2024-03-10 修正浮點比較誤差；2023-11-02 新增 3D 擴展介面
// 參考文獻: Computational Geometry in C (O'Rourke)
///////////////////////////////////////////////////////////////////////

#ifndef __GEOKERNEL_H__
#define __GEOKERNEL_H__
// ...
#endif

• 防重複包含護衛 (`#ifndef __FILENAME_H__`) 為強制要求。
• 修改歷史保留最近 3-5 條，完整歷史交由版控系統。

四、行內/區塊註解：關鍵節點必註，間隔 3-5 行

控制流程強制註解

// 1. 讀取設定檔
LoadConfig();

// 2. 初始化渲染器
if (!InitRenderer()) {
    // 2.1 失敗則回退軟體渲染
    FallbackToSoftware();
} else {
    // 2.2 成功載入著色器
    LoadShaders();
}

// 3. 進入主迴圈
while (running) {
    // 3.1 處理輸入
    ProcessInput();
    // 3.2 更新邏輯
    UpdateLogic();
    // 3.3 渲染幀
    RenderFrame();
}

• **序號前綴** (1./2./3.) 用於順序不可顛倒的流程。
• 迴圈、分支、switch 每個 case/default 必註。
• 一般代碼每 3-5 行一註解區塊功用。
• 個人獨特心得/優化技巧 **必須** 註明，防知識流失。

五、圖解輔助：複雜演算法/資料結構必圖

• 二元樹遍歷堆疊狀態圖、矩陣記憶體佈局圖、狀態機轉移圖。
• ASCII 藝術圖即可，嵌入註解區塊，編譯不受影響。

總結

註解不是「寫給編譯器看的廢話」，而是 **「寫給 6 個月後的自己、給新進同事、給代碼審查者」的導航地圖** 。函數頭六要素、變數語義化、檔案身分證、流程序號化、複雜邏輯圖解化 —— 五大支柱構建自文檔化代碼庫，讓維護從「考古」變成「導航」。