C++ 程式設計
有很多很好的理由去文件你的程式碼，還有很多程式碼可以被文件化的方面。文件為你提供了一個捷徑，讓你可以獲得系統的概述，或者理解提供特定功能的程式碼。
註釋的目的是向任何檢查它的人解釋和澄清原始碼（或者僅僅作為對你自己的一種提醒）。良好的註釋習慣對於任何非平凡的程式來說都是必不可少的，這樣閱讀程式碼的人就可以理解它預期做什麼，並使程式碼的其餘部分易於理解。在接下來的主題中，將為你列出一些使用註釋的 如何？ 和 何時？ 規則。
不僅在 C++ 中，在任何程式語言中，程式設計的文件都是必不可少的。許多公司已經從“英雄程式設計師”（即為整個公司編碼的單個程式設計師）的概念轉變為團隊合作的程式設計師群體的概念。很多時候，程式設計師只會在較大型專案的一部分上工作。在這種情況下，文件是必不可少的，因為
- 其他程式設計師可能被分配開發你的專案；
- 你的完成的專案可能會提交給編輯，以便將你的程式碼組裝到其他專案中；
- 除了你之外的人可能需要閱讀、理解和展示你的程式碼。
即使你不是為了謀生或為了公司而程式設計，文件你的程式碼仍然是必不可少的。儘管許多程式可以在幾個小時內完成，但更復雜的程式可能需要更長的時間才能完成（天、周等）。在這種情況下，文件是必不可少的，因為
- 你可能無法在一個會話中完成你的專案；
- 它提供你上次程式設計時所做更改的參考；
- 它允許你記錄你做出決定的 原因，包括為什麼你選擇 不 探索某些解決方案；
- 它可以提供一個記錄已知限制和錯誤的地方（對於後者，缺陷跟蹤系統可能是文件的合適地方）；
- 它允許在程式中輕鬆搜尋和引用（從非技術角度）；
- 它被認為是良好的程式設計實踐。
註釋應該針對合適的受眾。當編寫程式碼供那些處於學習新程式語言初始階段的人閱讀時，包含大量關於程式碼功能的註釋可能會有所幫助。對於“生產”程式碼，由專業人士閱讀的程式碼，包含已經清楚地顯示在程式碼中的註釋被認為是無用且適得其反的。來自 極限程式設計 社群的一些人說，過多的註釋表明存在 程式碼異味 -- 這並不意味著註釋不好，而是它們通常是程式碼需要 重構 的線索。將註釋作為編寫可理解程式碼的替代方案被認為是不好的做法。
在程式/原始碼中需要文件化的內容可以分為在特定程式執行之前（即在“main”之前）文件化的內容和執行的內容（“main 中的內容”）。
程式執行之前的文件
- 程式設計師資訊和許可證資訊（如果適用）
- 使用者定義的函式宣告
- 介面
- 上下文
- 相關標準/規範
- 演算法步驟
- 如何將原始碼轉換為可執行檔案（也許使用 make）
main 內部程式碼的文件
- 語句、迴圈和情況
- 類內的公共和私有部分
- 使用的演算法
- 實現的異常特徵
- 避免其他選擇的理由
- 使用者定義的函式實現
如果使用不當，註釋會使原始碼難以閱讀和維護，並且如果程式碼是自解釋的，註釋甚至可能是多餘的 -- 但請記住，今天看似自解釋的內容在六個月或六年後可能就不一樣了。
註釋應該文件決策。在你必須做出選擇的地方，新增一個註釋來描述你做出了什麼選擇以及原因。考古學家會發現這是最有用的資訊。
專案的每個部分都應該至少有一個註釋佈局，最好讓整個專案共享相同的佈局（如果可能的話）。
文件可以透過使用註釋（如上所示）在原始碼本身中完成，以目標受眾可以理解的語言進行。在英語中進行操作是好的做法，因為 C++ 語言本身是基於英語的，而英語是當前 通用語，用於國際商務、科學、技術和航空，你將確保為最廣泛的受眾提供支援。
註釋對於文件要執行的演算法部分、解釋函式呼叫和變數名稱或提供使用特定選擇或方法的原因很有用。塊註釋的使用方式如下
/*
get timepunch algorithm - this algorithm gets a time punch for use later
1. user enters their number and selects "in" or "out"
2. time is retrieved from the computer
3. time punch is assigned to user
*/
或者，可以使用行註釋，如下所示
GetPunch(user_id, time, punch); //this function gets the time punch
一個使用註釋作為文件的完整程式示例如下所示
/*
Chris Seedyk
BORD Technologies
29 December 2006
Test
*/
int main()
{
cout << "Hello world!" << endl; //predefined cout prints stuff in " " to screen
return 0;
}
需要注意的是，雖然註釋對於程式內文件很有用，但最好也有一種與原始碼分離的外部文件形式，但請記住在程式碼註釋中參考外部資訊之前先考慮原始碼的釋出方式。
註釋程式碼也不能替代經過精心策劃的、有意義的變數、函式和類名稱。這通常被稱為“自文件化程式碼”，因為很容易從精心選擇的描述性名稱中看出變數、函式或類的作用。為了說明這一點，請注意以下兩種文件化程式碼的方式的相對簡單的程度，儘管第一種使用了註釋，而第二種沒有使用註釋，但都易於理解。第一種風格經常出現在非常老的 C 原始碼中，編寫者非常清楚他們在做什麼，並且毫無疑問其他人可能不理解它。第二種風格更“人性化”，雖然更容易閱讀，但並不像以前那樣頻繁地遇到。
// Returns the area of a triangle cast as an int
int area_ftoi(float a, float b) { return (int) a * b / 2; }
int iTriangleArea(float fBase, float fHeight)
{
return (int) fBase * fHeight / 2;
}
這兩個函式執行相同的任務，但第二個函式為函式和變數選擇瞭如此實用的名稱，以至於即使沒有註釋，其目的也很清楚。隨著程式碼複雜度的增加，精心選擇的命名方案變得越來越重要。
無論採用何種方法，程式碼中的註釋都有助於節省時間（和頭痛），並確保作者和其他人充分理解程式的佈局和目的。
有多種工具可以幫助您記錄 C++ 程式碼；文學化程式設計 是一種完整的程式設計理念，但一個非常有效的工具是 Doxygen（也支援多種語言），它甚至可以使用手寫的註釋來生成超過程式碼基本結構的內容，將類似 Javadoc 的文件註釋引入到 C++ 中，並且可以生成 HTML、PDF 等格式的文件。
將您的註釋視為一個描述系統的故事。假設您的註釋會被機器人提取並整理成手冊頁面。類註釋是故事的一部分，方法簽名註釋是另一部分，方法引數是另一部分，方法實現又是另一部分。所有這些部分應該相互交織，並告知其他人，在未來的某個時間點，您究竟做了什麼以及為什麼這樣做。
- 不要使用註釋來繪製流程圖或編寫虛擬碼
您應該避免使用註釋來繪製 ASCII 藝術或編寫虛擬碼（一些程式設計師嘗試使用 ASCII 藝術流程圖來解釋他們的程式碼）。如果您想繪製流程圖或以其他方式對您的設計進行建模，可以使用其他工具，這些工具將使用標準化方法更好地完成這項工作。例如，參見：UML。