《C++面向對象高效程式設計（第2版）》——3.11 類名、成員函數名、參數類型和文檔

本節書摘來自異步社群出版社《c++面向對象高效程式設計（第2版）》一書中的第3章，第3.11節，作者： 【美】kayshav dattatri，更多章節内容可以通路雲栖社群“異步社群”公衆号檢視。

c++面向對象高效程式設計（第2版）

類通常被另一個程式員用來建立對象（或者通過繼承建立其他類），而方法則被這些對象（可能提供參數）調用。我們不僅要為類和其中所包含的方法提供有意義的名稱，還應該為成員函數的參數使用合适的名稱，這樣，客戶可以清楚地知道某個特别參數的用途。許多程式員隻指明函數接受的參數類型，而不給出名稱，必須改掉這個壞習慣。當然，編譯器不會在意你選擇什麼名稱，它隻負責比對類型。但是，參數名可以向客戶傳達許多資訊。除此之外，我們還要注意使用正确的參數傳遞模式（值、引用或指針）。

在大多數情況下，僅通過檢視名稱，無法清楚地了解類及其成員函數的用途。我們必須提供詳盡的文檔（documentation），其内容包括：

類的用途

預定使用者（打算給誰使用）

它所依賴的類（如果有）

類的限制是什麼

它期望從客戶方面獲得什麼1

在多線程系統中，還要進一步說明在多線程執行的環境中，類是否可用，這非常重要。大多數公司、項目和架構都要求類的設計者和實作者提供更多詳細的文檔。在設計和為類編寫文檔時，遵循所有的指導原則非常重要。

還有一點也至關重要，類的設計者（和實作者）必須非常清楚地說明建立對象的限制條件。例如，某些類要求隻能在運作時棧中建立類的對象（以確定自動銷毀）；而另一個類可能限制隻能在動态堆上建立對象（即對象必須隻能用new操作符建立）。這些對建立對象的限制不是很常見，但是，如果遇到也不必驚訝。用文檔說明建立對象的限制是個不錯的主意，但并不是最佳方案，最好是能通過語言強制執行這些限制。在c++中，控制對象在何處建立非常容易。實作它們的技巧将在第11章中介紹。

類中包含的每種方法，都需要一個類似的說明文檔。類文檔（class documentation）将客戶的注意力集中在一個方向，而且每種方法的文檔（或說明）進一步闡明了該方法在類中完成的工作。這樣的文檔不應該是一本厚厚的書，它可以是頭檔案中的簡單注釋（對于簡單方法），或是和類一起提供的輔助文檔。大文檔會讓客戶感到害怕，他們擔心類太複雜，難以了解（客戶認為正是這些原因導緻需要大的文檔），是以不願意使用它。一個設計優秀并帶有适宜說明的類将吸引客戶的注意力，并鼓勵她們使用。這類似于一個維護良好的公園，它引誘你入園漫步。在頭檔案中作簡明扼要的注釋非常有用，因為大多數程式員會首先在頭檔案中查找資訊。此外，每種方法也應指明它所接受的每個參數的用途。在使用引用和指針（大多數是指針）的情況下，必須清楚地定義存儲區所有權的職責（ownership responsibility），否則，會導緻記憶體洩漏或運作時崩潰，擾亂系統程式的正常運作。事實上，大部分與資源相關的問題都是由于類的實作者和使用者未明确各自的職責引起的。當方法傳回值（引用，指針或值）給調用者時，也需要明确地定義存儲區所有權職責。要養成盡可能使用const參數和const成員函數的習慣，因為編譯器能識别const元素，而且const可防止意外的修改。語言不能阻止惡意使用者的所作所為，它隻能防止使用者在使用時出現的意外錯誤。

你可能會問，為什麼要對文檔和參數傳遞如此小題大做？為什麼不能讓編譯器來處理這一切？問題是，很多程式員可以完成的事情，編譯器根本檢測不到。編譯器無法讀取你的想法，也不知道函數聲明中某個參數的用途。編譯器所能見的隻是類型名，它根本不關心函數的參數名。但是，對我們而言，這些參數名有實際意義。作為程式的設計者，我們在設計中将特定議題作為目标，并嘗試解決一些問題。編譯器完全不明白這些議題，對它而言，任何程式都是一系列的指令而已，它無法知曉“設計藍圖”。這就是文檔、約定（convention）和指導原則發揮作用的地方。

1這可能出人意料，但是許多類确實依賴客戶所提供的某些服務。

本文僅用于學習和交流目的，不代表異步社群觀點。非商業轉載請注明作譯者、出處，并保留本文的原始連結。