• 簡介
• 要求
  • 授權要求
  • 可攜性要求
  • 所有權
  • 組織
  • 整合
• 規範
  • 向下相容性
  • 設計與程式設計
  • 檔案名稱
  • 命名一致性
  • 文件
• 基本原理
  • 異常規範基本原理
  • 命名慣例基本原理
  • 原始碼字型基本原理
  • Tab 字元基本原理
  • 目錄和檔案名稱基本原理
  • ECMAScript/JavaScript 基本原理
  • 基本原理之基本原理
  • 致謝基本原理

簡介

此頁面描述提交到 Boost 的程式庫內容的要求和規範。

有關流程說明，請參閱 Boost 程式庫提交流程 頁面。

要求

為避免提議的程式庫被拒絕所造成的挫折和時間浪費，它必須符合以下要求

• 授權必須符合以下的 授權要求。像 GPL 和 LGPL 這樣的限制性授權是不可接受的。
• 版權 所有權 必須明確。
• 程式庫應該具有普遍的用途。
• 程式庫必須符合以下的 可攜性要求。
• 程式庫最好能符合以下的 組織要求。但在被接受後才需要符合這些要求。
• 程式庫必須相當程度地符合以下的 規範。
  • 設計與程式設計
  • 檔案名稱
  • 文件
• 作者必須願意參與郵件清單上的討論，並據此修改程式庫。

沒有要求作者在提交之前必須閱讀郵件清單一段時間。然而，值得注意的是，以「我剛開始閱讀這個郵件清單...」開頭的提交似乎都會失敗，而且常常令人尷尬。

授權要求

符合授權要求的首選方法是使用 Boost 軟體授權。請參閱 授權資訊。如果您因為任何原因不打算使用 Boost 軟體授權，請先在 Boost 開發者郵件清單 上討論這些問題。

授權要求

• 必須易於閱讀和理解。
• 必須免費授予複製、使用和修改軟體以用於任何用途（商業和非商業）的權限。
• 必須要求授權條款出現在所有軟體原始碼副本上。
• 不得要求授權條款與程式庫的可執行檔或其他二進制用途一起出現。
• 不得要求原始碼可供程式庫的可執行檔或其他二進制用途使用。
• 可以將程式庫的名稱和描述的使用限制在 Boost 網站上的標準版本。

可攜性要求

• 程式庫的介面必須可攜，且不限於特定的編譯器或作業系統。
• 程式庫的實作如果可能的話，必須可攜，且不限於特定的編譯器或作業系統。如果無法提供可攜的實作，則可以接受非可攜的建構，前提是這些建構相當容易移植到其他環境，並且至少為兩個常用的作業系統（例如 UNIX 和 Windows）提供實作。
• 程式庫至少在兩個實作最新 ISO C++ 標準的 C++ 編譯器上運行。
• 函式庫並不需要在不符合 ISO 標準的 C++ 編譯器上運行。
• 函式庫並不需要在任何特定的 C++ 編譯器上運行。Boost 貢獻者通常會努力確保他們的函式庫能與主流編譯器相容。 boost/config.hpp 設定標頭檔 是解決編譯器缺陷的首選機制。

由於沒有絕對的方法可以證明可移植性，許多 Boost 提交的程式碼會透過在兩個不同的 C++ 編譯器（通常在不同的作業系統下）正確編譯和執行來展現實際的可移植性。否則，審核者可能會質疑移植的實際可行性。

所有權

您確定您擁有您正在考慮提交的函式庫嗎？MJ Salone 於 1990 年出版的 Nolo Press 的《軟體版權指南》（How to Copyright Software）指出：

在您自己的時間進行與您為雇主在公司時間進行的程式設計非常相似的工作可能會引發棘手的法律問題。在這種情況下，最好事先獲得雇主的書面授權。

在您提交的所有重要檔案中加入版權聲明。Boost 不接受沒有明確版權資訊的函式庫。

組織結構

Boost 函式庫的品質不僅僅關乎 API 和程式碼設計，還關乎向所有函式庫的使用者呈現一致的觀感。函式庫在被接受後必須遵守以下目錄和檔案結構：

Boost 標準函式庫組織結構

子目錄或檔案	內容	必要性
build	函式庫建置檔案，例如 Jamfile、IDE 專案、Makefiles、Cmake 檔案等。	如果函式庫有需要建置的原始碼，則為必要。
config	用於建置時設定檢查的檔案。此目錄可能包含在建置函式庫、測試或範例時使用的原始碼檔和建置系統腳本，以檢查目標系統是否滿足特定條件。例如，檢查可能會測試編譯器是否實作了特定功能，或者目標系統是否支援特定 API。	選用。
doc	用於建置的原始碼和已建置的函式庫文件。如果函式庫需要從非 HTML 檔案建置文件，則此位置必須可以使用 Boost Build 進行建置。	所有函式庫皆為必要。
doc/html	文件（HTML）檔案。	所有具有預先生成文件的函式庫皆為必要。而且產生的文件必須在此處生成。
example	範例程式檔。	如果函式庫有範例檔案，則為必要，強烈建議提供。
index.html	重新導向至 HTML 文件。請參閱 「重新導向」 以取得此檔案的範本。	所有函式庫皆為必要。
include/boost/library	函式庫的標頭檔。	所有函式庫皆為必要。
meta	關於函式庫的後設資料。	所有函式庫皆為必要。
meta/libraries.json	一個包含函式庫資訊的 JSON 檔案，用於產生 Boost C++ 函式庫集合的網站和文件。	所有函式庫皆為必要。
meta/explicit-failures-markup.xml	描述預期測試失敗的 XML 檔案，用於產生測試報告。	選用
src	必須編譯才能建置函式庫的原始碼檔。	如果函式庫有需要建置的原始碼檔，則為必要。
test	迴歸測試或其他測試程式或腳本。這是自動化測試考量的*唯一*位置。如果您還有其他需要納入自動化測試的位置，則此位置必須參考其他測試位置。	所有函式庫皆為必要。
tools	函式庫使用或提供的工具。其內部結構由函式庫自行決定，但建議使用與一般 Boost 函式庫或工具相似的結構。	對於具有可執行工具的函式庫，這是必需的。

整合

一旦函式庫被 Boost C++ Libraries 接受，就必須使其正確整合到開發、測試、文件和發佈流程中。這種整合提高了所有函式庫的最終品質，並且是使用者期望 Boost C++ Libraries 整體品質的組成部分。除了上述的組織要求外，還需要以下整合：

建置原始碼

如果函式庫有需要建置的原始碼，則需要提供一個 Boost Build 專案，讓使用者和頂層 Boost 專案可以使用它來建置函式庫。用於原始碼建置的 Jamfile 至少需要宣告專案、函式庫目標，並註冊要安裝的目標。例如：

project boost/my_lib ;

lib boost_my_lib : a.cpp ;

boost-install boost_my_lib ;

測試

函式庫需要提供一個 Boost Build 專案，讓使用者和根 Boost 測試腳本可以使用它來建置和執行函式庫的測試。測試建置專案必須位於project-root/test目錄中，並且必須可以從這個目錄或其他目錄建置（例如，從 Boost 根目錄執行 `b2 libs/library/test` 必須可以正常運作。）

範例test/Jamfile如下所示

import testing ;

run default_constructor.cpp ;
run copy_constructor.cpp ;
compile nested_value_type.cpp ;
compile-fail invalid_conversion_1.cpp ;

*警告：* 這是頂層測試腳本唯一會考慮的測試位置。如果您想要測試其他位置，您必須宣告它們作為依賴項來建置，或者使用build-project.

如果函式庫需要一定程度的 C++ 標準一致性，而這排除了某些編譯器或配置的正常運作，則可以在測試Jamfile中宣告這些需求，以便不執行測試，以節省測試資源，如下例所示

import testing ;
import ../../config/checks/config : requires ;

project : requirements [ requires cxx11_variadic_templates cxx11_template_aliases ] ;

run cpp11_test.cpp ;

更多資訊，請參閱 Boost.Config 的文件。

建置文件

函式庫需要提供一個 Boost Build 專案來建置函式庫的文件。project-root/doc專案是頂層文件建置腳本和發佈建置腳本唯一參考的位置。文件建置專案必須具備以下兩個特性：

1. 定義一個boostdoc目標。此目標應該是一個別名，大致如下所示
   

   alias boostdoc : my_boostbook_target
       : : : <implicit-dependency>my_boostbook_target ;
   

   但如果您的專案沒有整合到全域文件書中，您可以使用一個空的別名，例如
   

   alias boostdoc ;
   

2. 如果專案有任何獨立文件，則專案必須預設建置獨立文件。發佈腳本會建置此預設值，以確保所有專案都具有最新的文件。

指導方針

請使用這些指導方針作為檢查清單，以準備提交函式庫的內容。並非每個指導方針都適用於每個函式庫，但預期會做出合理的努力來遵守。

回溯相容性

Boost 函式庫通常擁有龐大且多元的使用者群。為了確保在這種情況下能順利從舊 API 過渡到新 API，我們鼓勵函式庫作者在引入重大變更時遵循一些準則。

1. 非重大變更可以不受限制地進行。
2. 可以進行小的重大變更，但應在發布變更前的幾個版本中通知使用者。大多數重大變更都屬於此類。
3. 對於大型的重大變更：若有從舊 API 遷移到新 API 的路徑（例如`boost::filesystem`從 v2 到 v3），則應在單獨的目錄/命名空間中引入新 API，並應通知使用者並給予幾個版本的時間進行遷移。一段時間後可以移除舊 API。
4. 對於大型的重大變更：若沒有遷移路徑（例如`boost::spirit`從 v2 到 v3），則應在單獨的目錄/命名空間中提供新 API，並且應保留舊 API（因為沒有遷移路徑）。移除 API 應被視為與移除 Boost 函式庫相同，可以執行，但需要更長的棄用期。
5. 相當於重新設計或重寫函式庫的大型重大變更應被視為新的函式庫，並鼓勵進行正式審查（或至少是小型審查）。

設計與程式設計

首先追求清晰度和正確性；在大多數 Boost 函式庫中，優化應只是次要的考量。

以 ISO 標準 C++ 為目標。這意味著有效利用語言的標準特性，並避免使用非標準的編譯器擴充功能。這也意味著在適用情況下使用 C++ 標準函式庫。

標頭檔應該與其他程式碼良好共存。請參閱標頭檔政策。另請參閱命名一致性。

遵循優質的程式設計實務。例如，請參閱 Addison Wesley 出版社出版的 Scott Meyers 所著的《Effective C++》第二版和《More Effective C++》。

使用 C++ 標準函式庫或其他 Boost 函式庫，但僅限於效益大於成本的情況下。不要使用 C++ 標準函式庫或 Boost 以外的函式庫。請參閱函式庫重用。

閱讀實作變體，以了解如何提供效能、平台或其他實作變體。

瀏覽最佳實務手冊以獲取構想和現有 Boost 函式庫中原始碼的連結。

閱讀具有單獨原始碼的函式庫的準則，以了解如何確保編譯的連結函式庫符合使用者期望。

使用 C++ 標準函式庫的命名慣例（請參閱命名慣例的理由）

• 名稱（如下所述的除外）應全部小寫，單字之間用底線分隔。
• 縮寫應被視為普通名稱（例如，`xml_parser` 而不是 `XML_parser`）。
• 模板參數名稱以大寫字母開頭。
• 巨集（盡量避免使用！）名稱全部大寫，並以 `BOOST_` 開頭。

選擇有意義的名稱 - 清晰比含糊好，可讀性很重要。強烈建議使用清晰且具有描述性的名稱，即使名稱很長。

適當使用例外狀況來回報錯誤，並編寫在例外狀況發生時仍安全的程式碼。

避免使用例外規格。詳見例外規格說明。

提供範例程式或驗證測試，讓潛在使用者了解如何使用您的函式庫。

提供一個或多個回歸測試程式，遵循測試策略與協議。

雖然有些 Boost 成員在自己的程式碼中使用比例字型、定位點和不限行長，但廣泛發佈的 Boost 原始碼應遵循更保守的準則。

• 使用等寬字型。詳見字型說明。
• 使用空格而不是定位點。詳見定位點說明。
• 將行長限制在 80 個字元以內。

所有文件檔案（HTML 或其他格式）都應以版權聲明和授權聲明作為結尾。詳見授權資訊頁面以了解建議格式。

所有原始碼檔案（包括程式、標頭檔、腳本等）都應以以下內容開頭：

• 描述檔案內容的註解行。
• 描述版權和授權的註解：同樣地，建議格式請參考授權資訊頁面。
• 請注意，開發人員可以在其函式庫的儲存庫中，以 `LICENSE_1_0.txt`、`LICENSE.txt` 或 `LICENSE` 檔案提供授權文字副本。
• 在 Boost 網站上參考您的函式庫的註解行。例如：

  // See https://boost.dev.org.tw/libs/foo for library home page.
  

  其中 `foo` 是函式庫的目錄名稱（如下所述）。除了幫助那些偶然發現與其文件分離的 Boost 檔案的使用者之外，Boost 的一些自動化工具也依賴此註解來識別標頭檔屬於哪個函式庫。

**斷言：**如果您想在程式碼中加入執行時期斷言（您應該這麼做！），請避免使用 C 語言的 `assert` 巨集，而應使用 Boost 的 `BOOST_ASSERT` 巨集（位於 `boost/assert.hpp` 中）。它具有更高的可配置性。在公開標頭檔和函式庫原始碼（針對個別編譯的函式庫）中使用 `BOOST_ASSERT`。在範例和文件中使用 C 語言的 `assert` 巨集是可以的。

確保您的程式碼在存在 `min()` 和 `max()` 巨集的情況下仍能編譯。某些平台的標頭檔會定義 `min()` 和 `max()` 巨集，這會導致一些常見的 C++ 建構無法編譯。一些簡單的技巧可以保護您的程式碼免受不適當的巨集取代：

• 如果您要呼叫 `std::min()` 或 `std::max()`：
  • 如果您不需要引數依賴查找 (ADL)，請使用 `(std::min)(a,b)`。
  • 如果您需要引數依賴查找，您應該：
    • #include <boost/config.hpp>
    • 使用 `BOOST_USING_STD_MIN();` 將 `std::min()` 引入目前的範圍。
    • 使用 `min BOOST_PREVENT_MACRO_SUBSTITUTION (a,b);` 進行引數依賴的 `min(a,b)` 呼叫。
• 如果您要呼叫 `std::numeric_limits<int>::max()`，請改用 `(std::numeric_limits<int>::max)() `。
• 如果您要呼叫名為 `min()` 或 `max()` 的成員函式，請使用 `(obj.min)() `，而不是 `obj.min()`。
• 如果您要宣告或定義名為 `min` 或 `max` 的函式或成員函式，則必須使用 `BOOST_PREVENT_MACRO_SUBSTITUTION` 巨集。不要寫 `int min() { return 0; }`，而應該寫 `int min BOOST_PREVENT_MACRO_SUBSTITUTION () { return 0; }`。無論該函式是自由函式（命名空間範圍）、成員函式還是靜態成員函式，都是如此，並且它適用於函式宣告以及函式定義。

檔案名稱

命名要求確保檔案和目錄名稱具有相對的可攜性，包括 ISO 9660:1999（含副檔名）和其他相對受限的檔案系統。提供上標連結以詳細說明每個選擇的理由。

• 名稱只能包含小寫¹ ASCII 字元 ('a'-'z')、數字 ('0'-'9')、底線 ('_')、連字號 ('-') 以及句點 ('.')。不允許使用空格²。
• 目錄名稱不能包含句點 ('.')³。
• 檔案名稱的第一個和最後一個字元不能是句點 ('.')⁴。
• 名稱的第一個字元不能是連字號 ('-')⁵。
• 目錄和檔案名稱的最大長度為 31 個字元⁶。
• 總路徑長度不能超過 207 個字元⁷。

其他慣例有助於溝通

• 打算由 C++ 編譯器作為翻譯單元一部分處理的檔案，其檔案名稱應為三個字母，並以 "pp" 結尾。其他檔案不應使用以 "pp" 結尾的副檔名。此慣例可以輕鬆識別 Boost 中的所有 C++ 原始程式碼。
• 所有程式庫在其最高層級都有一個以特定程式庫命名的主要目錄。請參閱命名一致性。主要目錄可能包含子目錄。

重新導向

主要目錄應始終包含一個名為 index.html 的檔案。作者要求這樣做，以便他們可以發佈格式為 *https://boost.dev.org.tw/libs/程式庫名稱* 的網址，並確保文件重組不會使網址失效。Boost 的內部工具也因為知道程式庫的文件始終可以透過簡化的網址存取而得到簡化。

主要目錄的 index.html 檔案應該只執行自動重新導向到 doc/html 子目錄。

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">

<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
<head>
  <title>Boost.Name Documentation</title>
  <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
  <meta http-equiv="refresh" content="0; URL=doc/html/index.html" />
</head>

<body>
  Automatic redirection failed, please go to <a href=
  "doc/index.html">doc/index.html</a>
</body>
</html>

命名一致性

隨著程式庫開發人員和使用者在 Boost 上累積經驗，以下一致的命名方法被認為非常有幫助，尤其是對於需要自己的標頭檔子目錄和命名空間的大型程式庫。

以下是它的運作方式。程式庫的名稱應該描述程式庫的內容。強烈建議不要使用難以理解的縮寫。遵循 C++ 標準程式庫的慣例，名稱通常使用單數而不是複數。例如，處理檔案系統的程式庫可能會選擇名稱 "filesystem"，而不是 "filesystems"、"fs" 或 "nicecode"。

• 程式庫的主要目錄（位於父目錄 boost-root/libs 中）使用相同的名稱。例如，boost-root/libs/filesystem。
• 程式庫的主要標頭檔目錄（位於 boost-root/libs/名稱/include 中）使用相同的名稱。例如，boost-root/libs/filesystem/boost/filesystem。
• 程式庫的主要命名空間（位於父命名空間 *::boost* 中）使用相同的名稱，但當存在具有該名稱的元件時（例如，*boost::tuple*），命名空間名稱則使用複數形式。例如，*::boost::filesystem*。

在編寫 Boost 程式庫文件時，請遵循以下慣例（另請參閱本文檔的下一節）

• 程式庫名稱以羅馬字體顯示。
• 程式庫名稱的首字母大寫。
• 僅當程式庫名稱後面沒有 "library" 一詞時，才在 "Boost" 和程式庫名稱之間使用句點（例如，Boost.Bind）。
• "library" 一詞不是程式庫名稱的一部分，因此小寫。

以下是如何應用這些慣例的一些範例

• Boost.Bind 由 Peter Dimov 撰寫。
• Boost Bind 函式庫是由 Peter Dimov 所撰寫的。
• 我經常使用 Bind，一個由 Peter Dimov 撰寫的 Boost 函式庫。

文件

即使是最簡單的函式庫也需要一些文件；文件量應該與需求成正比。文件應該假設讀者具備 C++ 的基本知識，但不一定是專家。

文件的格式應為 HTML，且不應要求進階的瀏覽器或伺服器端擴充功能。樣式表是可以接受的。不建議使用 ECMAScript/JavaScript。文件的入口點應該始終是一個名為 index.html 的檔案；請參閱重新導向。

撰寫文件沒有單一的正確方法。HTML 文件的組織方式通常與傳統印刷文件大不相同。以任務為導向的風格與以參考為導向的風格不同。最終，問題歸結為：文件是否足以讓傳說中的「一般」C++ 程式設計師成功地使用函式庫？

適當的文件主題通常包括

• 函式庫的概述。導論尤其需要包含
  • 一個非常高層次的概述，說明函式庫的用途，以及可能不適用的情況，即使是對問題領域沒有任何先驗知識的人也能理解。
  • 使用函式庫的最簡單範例（「hello world」）。
• 涵蓋基本使用案例的教學。
• 參考文件
  • 每個類別的描述。
  • 類別之間的關係。
  • 對於每個函式，依情況說明其描述、需求（前置條件）、效果、後置條件、返回值和拋出的例外。
  • 錯誤偵測和恢復策略的討論。
• 如何編譯和連結。
• 如何測試。
• 版本或修訂歷史記錄。
• 設計決策的原理說明。請參閱原理說明。
• 致謝。請參閱致謝說明。

如果您需要更多關於如何撰寫文件的幫助，您可以查看關於為 Boost 撰寫文件的文章。

原理說明

以下說明一些需求和指導方針的原理。

例外規範的原理說明

例外規範 [ISO 15.4] 有時會被編碼以指示可能會拋出哪些例外，或者因為程式設計師希望它們能提高效能。但請考慮以下來自智慧指標的成員

T& operator*() const throw()  { return *ptr; }

這個函式沒有呼叫其他函式；它只操作基本資料類型，例如指標。因此，永遠不會叫用例外規範的執行時期行為。該函式完全暴露給編譯器；實際上，它被宣告為 inline。因此，智慧編譯器可以很容易地推斷出這些函式無法拋出例外，並進行與基於空例外規範相同的最佳化。「笨拙的」編譯器可能會進行各種負面最佳化。

例如，如果存在例外規範，某些編譯器會關閉 inline 化。有些編譯器會新增 try/catch 區塊。這種負面最佳化可能會造成效能災難，使程式碼在實際應用中無法使用。

雖然一開始很吸引人，但例外規範往往會產生需要非常仔細思考才能理解的後果。例外規範最大的問題是程式設計師使用它們的方式，就好像它們具有程式設計師想要的效果，而不是它們實際具有的效果。

非 inline 函式是在某些編譯器中，「不拋出任何東西」的例外規範可能有一些好處的地方。

命名慣例的根本原因

C++ 標準委員會的程式庫工作小組針對這個議題進行了長時間的詳細討論。在 Boost 早期的貼文中也重複討論過這個議題。簡要概述如下：

• 命名慣例一直備受爭議，雖然有幾種慣例被廣泛使用，但沒有一種風格佔據主導地位。
• 鑒於提議將 Boost 的部分內容納入下一個 C++ 標準程式庫版本的意圖，Boost 決定遵循標準程式庫的慣例。
• 一旦一個程式庫確定了特定的慣例，絕大多數的利益相關者都希望該風格能夠被一致地使用。

原始碼字型的根本原因

Dave Abrahams 的評論：原始碼的一個重要目的（我敢說是主要目的）是溝通：記錄意圖。我認為，對於 Boost 來說，這是一個雙重重要的目標。使用等寬字型可以讓我們在原始碼中以更多的方式與更多人進行溝通（例如可以使用圖表）。使用空格為等寬字型編寫的程式碼，在使用變寬字型檢視時也能夠良好地閱讀，而且據我所知，每個支援變寬字型的編輯器也都支援等寬字型。我不認為反之亦然。

Tab 字元的根本原因

禁止使用 Tab 字元是因為在 Boost 這樣的多開發者專案中，Tab 字元會造成實際問題，而不是原則上的厭惡。詳見郵件列表存檔。問題包括使用 Tab 字元的程式設計師和使用空格的程式設計師維護同一個原始碼檔案，以及難以執行一致的 Tab 字元策略（除了「禁用 Tab 字元」之外）。討論的結論是，Boost 檔案應該全部使用 Tab 字元或全部使用空格，因此決定繼續使用空格進行縮排。

目錄和檔案名稱的根本原因

1.某些舊的檔案系統要求使用單一大小寫的名稱。單一大小寫的名稱可以避免在從大小寫不敏感的檔案系統遷移到大小寫敏感的檔案系統時出現大小寫錯誤。

2.這是 POSIX 可攜式檔名字元集的小寫部分。引用 POSIX 標準，「檔名應該由可攜式檔名字元集構成，因為在某些情況下，使用其他字元可能會造成混淆或歧義。」

3.ISO 9660:1999 的嚴格實作以及一些舊的作業系統禁止在目錄名稱中使用點。這種限制的需求正在消失，而且很可能很快就會被移除。

4.POSIX 對以句點開頭的名稱有特殊的規則。Windows 禁止以句點結尾的名稱。

5.在某些情況下可能會造成混淆或歧義。

6.我們必須在某處劃定界線，因此多年前選擇了現在已經過時的 Apple 檔案系統所施加的限制。為了便於人們理解，這仍然是一個合理的限制。

7.ISO 9660:1999。

ECMAScript/JavaScript 的根本原因

在 1.29.0 版本之前，兩個 Boost 程式庫添加了 ECMAScript/JavaScript 文件。隨後引發了爭議（請參閱郵件列表存檔），並要求開發人員移除 ECMAScript/JavaScript。禁用 ECMAScript/JavaScript 的原因包括：

• 與某些較舊的瀏覽器和某些基於文字的瀏覽器不相容。
• 讓文件頁面難以列印。
• 通常會導致非常糟糕的使用者介面設計。
• 「總之就是很煩人。」
• 需要 Boost 去測試網頁的 ECMAScript/JavaScript 相容性。
• 讓文件維護變得更加困難，尤其是對於原始開發者以外的人。

如果您決定必須使用 JavaScript，請考慮這些原因。尤其請記住，Boost 社群不負責測試您對 JavaScript 的使用。因此，您有責任確保在您的使用案例中完全解決上述問題。

允許使用 ECMAScript/JavaScript，但不鼓勵，理由如上。

基本原理說明

根據美國傳統詞典，基本原理的定義是「某事的根本原因；基礎」。

Beman Dawes 評論：未能提供設計決策的當代基本原理是許多軟體專案的主要缺陷。缺乏準確的基本原理會導致問題被無休止地重新審視，導致維護人員在更改某些內容時，因為沒有意識到它是基於某種目的以某種方式完成的而造成錯誤，並縮短軟體的使用壽命。

在做出決策時，提供基本原理相當容易，但在即使是很短的時間之後，要準確地恢復基本原理卻非常困難。

致謝說明

隨著函式庫的成熟，它幾乎總是會累積其他 Boost 成員向作者建議的改進。Boost.org 的文化一部分是承認此類貢獻，並指明提出建議的人。主要的貢獻通常會在文件中得到承認，而小的修正通常會在程式碼本身的註釋中提及。