文件編寫

一個成功的程式庫，好的文件是至關重要的！一般需要文件：設計文件，使用指南和參考手冊。

文件編制和重用性

沒有經過適當文件化的程式碼不能成為可重用程式碼，一個設計得很好的程式庫，如果文件編制得好，那麼將會是一個文件齊全的程式庫，否則會功虧一簣，對於希望快速學會如何使用程式庫的使用者而言，好的文件是必不可少的。就算是小規模的程式庫，也不應該忽視文件的編寫。衡量一個好的程式庫的文件，如果設計和實現相同功能新程式庫的時間比學習這個程式庫的時間要多得多，這個程式庫才是成功的！
編制高質量的文件通常都會佔用設計、實現和測試程式很大的一部分時間，之所以需要編制好的文件，主要是由於開發可重用程式碼的開銷要比開發單一用途程式碼的開銷多很多。
每一個可重用的C++程式庫都至少應該附帶設計檔案、使用指南和參考手冊。

設計文件

C++程式庫的設計文件至少應該回答下列問題：
1、程式庫提供了哪些類
2、繼承體系如何
3、程式庫的所有類是否都是nice類
4、程式庫的效率如何
5、在什麼條件下，程式庫才是可擴充套件的
6、該程式庫是否使用了其他程式庫？如果是，那麼該程式庫已經測試了其他程式庫的那些版本？
7、程式庫是否具有向前或者向後的原始碼程式碼相容性、連結相容性、執行相容性或者程式相容性？
8、程式庫的錯誤處理機制如何
9、程式的可移植性如何
10、該程式庫是否會和其他程式庫發生衝突

使用指南

使用指南的用途是在於幫助使用者可以學會使用這個程式庫，因此它省略了許多關於程式庫的高階或者特殊用法方面的細節。提供一個用於整個程式庫的使用指南，而且還應該為程式庫的每個類或者相關類的集合提供單獨的使用指南。
編寫使用指南幾乎就是一門藝術，學習這種藝術最好的方法就是閱讀他人寫得好的使用指南，然而仿照寫出自己程式庫的使用指南。
1、對讀者的背景知識瞭如指掌，注意用語或者說要用通俗化語言
2、用抽象的觀點來編寫。編寫的函式行為應該依據它們對物件抽象值得影響，而不是依據它們的底層實現，應當給出高層解釋！
3、先解釋普通用法。並不是所有的功能都必須加以解釋，更不用不分輕重地解釋。指南通常只需要給出讓使用者知道如何開始操作的知識，和使用者經常希望使用的功能等方面的知識。
4、一次只解釋一個事物。冗雜太多不利用使用者快速上手。
5、只解釋用法，不解釋設計思路
6、簡單清楚地編寫
7、準確地使用語言
8、使用普遍接受的術語
9、深刻理解過載的術語
10、給出合法的、無錯誤的程式碼。使用指南中的程式碼不應該存在無意的錯誤，如果出現語法或者邏輯錯誤，那隻能說明沒有對程式碼例子進行嚴格的測試。程式碼編寫者是非常粗心和懶惰的，從而也會導致使用者對程式庫或使用指南失去信心，或者對兩者都失去信心。
11、保持簡短的程式碼段。程式碼例子越長，使用者跳過這段程式碼或者產生疑惑的可能性就越大。如果需要說明觀點需要很多行程式碼，那麼應該用代替的文字把這些程式碼分開！通過文字解釋，對程式碼塊進行切割！
12、避免使用太大的函式。如果函式實在是大，那麼使用整體和區域性另外說明的方式！
13、提供線上例項。

參考手冊

大多數C++程式庫主要是由類的集合組成的，因此，程式庫文件的編寫者應該知道如何完整、準確地文件化一個類。總而言子類X的文件應該包含下列幾個方面：（Qt的參考手冊）
1、告訴使用者需要#include哪些檔案才能得到類X的定義。除非有充分的理由採用其他方式，否則程式庫的每個公共標頭檔案都應該#include或者申明它所需要的物件。採用這種方法後，我們就不會為了得到某個類的定義，而需要#include多個標頭檔案。
2、定義類X的抽象
3、給出類X的語法介面
4、描述X介面中每個函式的語義
5、宣告任何對模板引數的限制條件

抽象化
清晰定義每個類的抽象，不管多麼過分強調，都是合情合理的。為了可以巧妙地使用某個樓，使用者必須先知道這個類所模擬的抽象。

語法介面
類裡面函式介面的型別，以及許可權，引數，返回值

函式語義
1、語義的解釋應該依據給物件的抽象值，而不是物件底層實現
2、當文件化虛擬函式的時候，還應該指定它的繼承語義
3、當返回型別為指標或引用的函式被文件化時，應該指出這個返回值的生存期
4、如果函式丟擲異常，還應該指定每個異常的型別和這個異常的丟擲條件

模板引數約束
任何對類别範本引數或者函式模板引數的約束，都應該在參考手冊中進行文件化！對引數的說明！