BCB 軟體編碼規範：提升程式碼品質與團隊協作

前言

建立編碼規範旨在形成團隊慣例，提高程式可靠性、可讀性、可維護性、一致性，保證品質，促進成果重用與共享。遵循開發流程、實現設計功能與效能、良好結構與封裝、低耦合、易測試、易維護擴充、資源節約、效率與可讀性平衡。

一、源程式檔案管理

組織原則

• 單元通常由 .cpp、.dfm、.h 組成，公共宣告置於 .h。
• 以類別為劃分依據，大類別獨立單元，小型緊密相關類別可合併（建議僅限充分測試的通用類別）。

命名規範

採用有意義格式，如登入程式：Login.cpp、Login.dfm、Login.h。

檔案結構：標題、內容、附加說明

• 標題：程式名、作者、版本、簡要說明，必要時詳細說明 (空行隔開)。
• 內容：依預處理、型別定義、變數定義、函數原型、函數實作 (僅 .cpp) 順序。main/WinMain、控件註冊置最後。類別定義按 private → protected → public → __published，各區塊按資料、函數、屬性、事件順序，盡量每區塊只有一個。
• 附加說明：檔案末尾補充，如參考資料，內容少可併入標題末尾。

範例：標題區塊

/*************************************************************
類別：class TImageManipulation
設計者：lunhongjun (2001/05/09)
用途：影像處理，亮度/對比/反白/色彩平衡等
版本：
1.0 2001/05/09 完成基本功能
2001/05/10 修正一個小 Bug
*************************************************************/

範例：類別定義結構

class TImageManipulation {
private: // 資料成員
    Graphics::TBitmap *pSourceBitmap;
    Graphics::TBitmap *pManipulatedImage;
    int iBrightness, iContrast;
    int iRedColorBalance, iBlueColorBalance, iGreenColorBalance;
    bool bRotate, bMonochrome;
private: // 私有方法
    void __fastcall BrightnessImage(void);
    void __fastcall ContrastImage(void);
    // ...
public: // 公開介面
    __fastcall TImageManipulation();
    __fastcall ~TImageManipulation();
    void __fastcall DoBrightness(int BrightnessIncrement);
    // ...
    TImageManipulation& operator=(const TImageManipulation & imSource);
};

二、編輯風格

縮排

4 空格為單位，Tools/Editor Options 設定 Block indent=4, Tab Stop=4，不勾選 Use tab character。預處理、全域資料、函數原型、標題、說明、標號頂格。區塊 { } 配對對齊，獨佔一行，區塊內語句縮排。

空格

• 型別、修飾詞、名稱間適當空格對齊。
• 關鍵字原則空一格：if ( ... )。
• 運算子空格規則：:: -> [] ++ -- ~ ! + - (正負) & (取址) * (指標) 兩側不加空格；其他二元/三元運算子兩側加一空格；( ) 內側空一格；, 後空一格；sizeof 後建議空一格；行尾註解適當空格隔開對齊。

對齊

關聯行對齊 (型別、修飾、名稱、參數)。行長不超過螢幕太多，換行盡量在 , 或運算子處，換行後以運算子開頭，以下各行同首行縮排。

int Value;
int Result;
int Length;
DWORD Size;
DWORD BufSize;
char *pBuf;
void *pOutputBuf;
LPCSTR *pPath;

空行

• 檔案結構各部份間空兩行 (或一行)。
• 函數實作間空兩行 (BCB 自動產生 //------ 分隔)，通常空一行或不空；無函數說明時至少空一行。
• 函數內資料與代碼間至少空一行，代碼適當處空行分隔，變數宣告前空一行。
• 類別四個 p 區塊間至少空一行，資料與函數間空行。

註解

三原則：有意義、正確描述、最新。四種必要註解：標題/附加說明、函數說明 (功能、目的、演算法、參數、回傳值、特殊需求、修改日誌)、不明確/不可移植處說明、少量其他。區塊註解 /**/ 用於標題，行註解 // 用於少量，函數說明統一風格。

程式碼長度

單一函數建議控制在 53 行以內，超過需拆分。拆分不破壞演算法，拆出部分可重用。跨模組/視窗重複代碼獨立為公用函數置於 Common.cpp/h。

三、符號命名規範

原則

採用有實際意義的英文識別字或縮寫，避免阿拉伯數字 (如 Value1, Value2...)。例：file, code, data, pagepoint, faxcode, address, bank...。

變數命名：前綴 + 修飾語

• 生存期修飾：l (local)、p (public/global)、s (send/參數)。
• 型別修飾：s (AnsiString)、c (Char)、n (Number)、i (Integer)、d (Double)、f (Float)、b (Bool)、d (Date)。

例：li_length (區域整數長度)、ls_code (區域字串代碼)。

控件命名：前綴 + 修飾語

註：表相關控件修飾語建議直接用表名。

四、輸入輸出與介面設計

• 方式格式方便使用者，完備錯誤檢查與恢復。
• 介面佈局：必要資訊完整、左上角開始、統一標準、邏輯關聯分組、對稱平衡、減少前置調整、區分標題內容、提示簡潔、符合用戶經驗、按使用順序顯示、遵循事實標準、合理顯示方式、單畫面完成完整操作。

五、其他程式技巧

• 適量有意義註解，列入評鑑指標。
• 全面考慮例外處理，良好錯誤/例外機制，保證正常運行/退出、資料不丟失、記錄運行狀況可回報。
• 避免相似變數名、變數含數字、同名多義、隱含宣告。
• 注意浮點誤差、整數特性，少用 GOTO (不交叉)、全域/靜態變數。
• 提高封裝性、降低耦合、提高可繼承性、建立通用函數庫/控件庫共享成果。

版權聲明

設計者：luhongjun (過江項羽)。文檔版權歸 BCB 開發團隊，歡迎轉載引用並註明來源，未經同意勿修改、勿商業使用。