慣例

本節提供一些關於我們用來解決 C++ 專案許多部分常見問題的抽象概念和開發方法的資訊。

檔案命名

C++ 原始碼和標頭檔應使用底線分隔單字，而非連字符號。然而，編譯後的可執行檔將自動使用連字符號（例如，src/arrow/scalar_test.cc 將被編譯成 arrow-scalar-test）。

C++ 標頭檔使用 .h 副檔名。任何不包含 internal 的標頭檔名稱都被視為公開標頭，並將由建置系統自動安裝。

註解與文件字串

一般註解以 // 開頭。

Doxygen 文件字串以 /// 開頭，而 Doxygen 指令以 \ 開頭，如下所示

/// \brief Allocate a fixed size mutable buffer from a memory pool, zero its padding.
///
/// \param[in] size size of buffer to allocate
/// \param[in] pool a memory pool
ARROW_EXPORT
Result<std::unique_ptr<Buffer>> AllocateBuffer(const int64_t size,
                                               MemoryPool* pool = NULLPTR);

文件字串的摘要行使用原形動詞，而非直陳式動詞（例如，「Allocate a buffer」而非「Allocates a buffer」）。

記憶體池

我們提供一個預設記憶體池，使用 arrow::default_memory_pool()。

錯誤處理與例外

對於錯誤處理，我們返回 arrow::Status 值，而不是拋出 C++ 例外。由於 Arrow C++ 函式庫旨在作為大型 C++ 專案中的組件使用，因此使用 Status 物件可以透過明確指出函數預期可能失敗的情況，來幫助保持良好的程式碼衛生。

一個較新的選項是返回 arrow::Result<T> 物件，它可以表示一個成功的結果（帶有 T 值）或一個錯誤結果（帶有 Status 值）。

為了表達內部不變性和「不會失敗」的錯誤，我們使用在 arrow/util/logging.h 中定義的 DCHECK 巨集。這些檢查在發布版本中被禁用，旨在捕捉內部開發錯誤，特別是在重構時。這些巨集不應包含在任何公開標頭檔中。

由於我們不使用例外，因此我們避免在物件建構子中執行昂貴的工作。建構成本高的物件通常可能具有私有建構子，以及返回 Status 或 Result<T> 的公開靜態工廠方法。

有許多物件建構子，例如 arrow::Schema 和 arrow::RecordBatch，在其中可能會建立較大的 STL 容器物件，例如 std::vector。雖然在這些建構子中可能會拋出 std::bad_alloc，但拋出的情況有些特殊，且應用程式很可能在建構子中拋出 std::bad_alloc 之前就遇到了其他更嚴重的問題。