編程規範的工程價值
統一、鮮明的編程風格讓協作者、後繼者、未來的自己能在極短時間內看清結構、理解設計意圖，大幅提升代碼可讀性、可重用性、健壯性、可移植性、可維護性。本規範涵蓋程序風格、命名、註釋、健壯性、可移植性、錯誤處理、模塊化七大維度。
文件結構規範
雙文件架構
| 文件類型 | 用途 | C後綴 | C++後綴 |
|---|
| 頭文件 | 聲明 | .h | .h |
| 定義文件 | 實現 | .c | .cpp (.cc/.cxx) |
文件信息聲明（文件頭部）
/*
* 版權信息：Copyright (C) 2024 Company Name. All rights reserved.
* 文件名稱：module_name.h
* 項目代碼：PRJ-2024-001
* 摘要：核心數據結構與接口聲明
* 參考文獻：ISO/IEC 14882:2020, Internal Doc ARCH-001
* 當前版本：v2.3.1
* 作者/修改者：Zhang San
* 完成日期：2024-03-15
* 版本歷史：
* v1.0 2023-01-10 Li Si 初始版本
* v2.0 2023-11-20 Wang Wu 重構接口，增加異常安全保證
* v2.3 2024-03-01 Zhang San 修復邊界條件Bug #1245
* 主要函數：init_module(), process_data(), cleanup_module()
*/
命名規範核心原則
| 實體 | 風格 | 示例 | 備註 |
|---|
| 類/構造體 | PascalCase | UserManager, DataPacket | 名詞，體現職責 |
| 函數/方法 | camelCase | calculateTotal(), parseConfig() | 動詞開頭，體現行為 |
| 變量/參數 | snake_case | user_count, max_retry_times | 名詞，清晰表達含義 |
| 常量/宏 | UPPER_SNAKE_CASE | MAX_BUFFER_SIZE, DEFAULT_TIMEOUT | 全大寫，單位隱含 |
| 模板參數 | PascalCase + _T | ValueType_T, Allocator_T | 區分普通類型 |
| 私有成員 | snake_case + _ | buffer_size_, config_ptr_ | 尾部下劃線區分 |
註釋規範：Doxygen風格
/**
* @brief 計算兩個整數的最大公約數
* @param a 第一個整數，必須非負
* @param b 第二個整數，必須非負
* @return 最大公約數，若a=b=0返回0
* @throws std::invalid_argument 若參數為負數
* @note 使用輾轉相除法，時間複雜度O(log min(a,b))
*/
int gcd(int a, int b);
健壯性與錯誤處理
- 契約式設計：前置條件(斷言/異常)、後置條件、不變量
- 資源管理：RAII原則，智能指針/容器自動管理，禁用裸
new/delete
- 異常安全：基本承諾(不洩漏)、強烈承諾(事務語義)、不拋出承諾
- 錯誤碼vs異常：預期錯誤用
std::expected(C++23)/錯誤碼，異常情況用異常
可移植性指南
- 依賴標準庫而非平台API
- 用
<cstdint>定寬類型替代int/long
- 避免數據結構位域、聯合體依賴佈局
- 文件路徑用
std::filesystem(C++17)處理分隔符差異
- 編譯器擴展用
#ifdef隔離，提供標準回退實現
