注釋
軟體文檔以兩種形式存在：外部的和內部的。外部文檔（如規範、協助檔案和設計文檔）在原始碼的外部維護。內部文檔由開發人員在開發時在原始碼中編寫的注釋組成。
不考慮外部文檔的可用性，由於硬拷貝文檔可能會放錯地方，原始碼清單應該能夠獨立存在。外部文檔應該由規範、設計文檔、變更要求、錯誤記錄和使用的編碼通訊協定組成。
內部軟體文檔的一個難題是確保注釋的維護與更新與原始碼同時進行。儘管正確注釋原始碼在運行時沒有任何用途，但這對於必須維護特別複雜或麻煩的軟體片段的開發人員來說卻是無價的。
以下幾點是推薦的注釋方法：
- 如果用 C# 進行開發，請使用 XML 文檔格式，如下面方法的注釋：
/// <summary>
/// 得到某人的年齡
/// </summary>
/// <param name="userName">使用者名稱</param>
/// <returns>使用者年齡</returns>
public int GetUserAge(string userName)
{
//
//此處寫你的程式碼
//
}
- 修改代碼時，總是使代碼周圍的注釋保持最新。
- 在每個常式的開始，提供標準的注釋樣本以指樣本程的用途、假設和限制很有協助。注釋樣本應該是解釋它為什麼存在和可以做什麼的簡短介紹。
- 避免在程式碼的末尾添加註釋；行章節附註釋使代碼更難閱讀。不過在批註變數聲明時，行章節附註釋是合適的；在這種情況下，將所有行章節附註釋在公用製表位處對齊。
- 避免雜亂的注釋，如一整行星號。而是應該使用空白將注釋同代碼分開。
- 避免在塊注釋的周圍加上印刷框。這樣看起來可能很漂亮，但是難於維護。
- 在部署之前，移除所有臨時或無關的注釋，以避免在日後的維護工作中產生混亂。
- 如果需要用注釋來解釋複雜的代碼節，請檢查此代碼以確定是否應該重寫它。盡一切可能不注釋難以理解的代碼，而應該重寫它。儘管一般不應該為了使代碼更簡單以便於人們使用而犧牲效能，但必須保持效能和可維護性之間的平衡。
- 在編寫注釋時使用完整的句子。注釋應該闡明代碼，而不應該增加多義性。
- 在編寫代碼時就注釋，因為以後很可能沒有時間這樣做。另外，如果有機會複查已編寫的代碼，在今天看來很明顯的東西六周以後或許就不明顯了。
- 避免多餘的或不適當的注釋，如幽默的不主要的備忘。
- 使用注釋來解釋代碼的意圖。它們不應作為代碼的聯機翻譯。
- 注釋代碼中不十分明顯的任何內容。
- 為了防止問題反覆出現，對錯誤修複和解決方案代碼總是使用注釋，尤其是在團隊環境中。
- 對由迴圈和邏輯分支組成的代碼使用注釋。這些是協助原始碼讀者的主要方面。
- 在整個應用程式中，使用具有一致的標點和結構的統一樣式來構造注釋。
- 用空白將注釋同注釋分隔字元分開。在沒有顏色提示的情況下查看注釋時，這樣做會使注釋很明顯且容易被找到。
