預估時間： 10 分鐘

好的範例程式碼通常是最好的文件。即使您的段落和清單清晰如水，程式設計師仍然偏好好的範例程式碼。畢竟，文字和程式碼是不同的語言，而讀者最終關心的是程式碼。試圖用文字描述程式碼，就像試圖用英文解釋一首義大利詩歌一樣。

好的範例程式碼是正確且簡潔的程式碼，您的讀者可以快速理解並輕鬆重複使用，且副作用最小。

正確

範例程式碼應符合以下標準：

• 編譯無錯誤。
• 執行其聲稱要執行的任務。
• 盡可能接近生產環境。例如，程式碼不應包含任何安全漏洞。
• 遵循特定語言的慣例。

範例程式碼是直接影響使用者撰寫程式碼方式的機會。因此，範例程式碼應設定使用您產品的最佳方式。如果有多種方式可以編寫任務程式碼，請以您的團隊認為最佳的方式編寫。如果您的團隊尚未考慮每種方法的優缺點，請花時間這樣做。

務必測試您的範例程式碼。隨著時間的推移，系統會發生變化，您的範例程式碼可能會失效。請準備好像測試和維護任何其他程式碼一樣測試和維護範例程式碼。

許多團隊將其單元測試重複用作範例程式，這有時是個壞主意。單元測試的主要目標是測試；範例程式的唯一目標是教育。

程式碼片段是範例程式的一部分，可能只有一行或幾行長。大量使用程式碼片段的文件通常會隨著時間的推移而劣化，因為團隊往往不會像測試完整的範例程式那樣嚴格地測試程式碼片段。

執行範例程式碼

好的文件會解釋如何執行範例程式碼。例如，您的文件可能需要告訴使用者在執行範例之前執行以下活動：

• 安裝特定函式庫。
• 調整分配給某些環境變數的值。
• 調整整合開發環境 (IDE) 中的某些設定。

使用者不一定總是正確執行上述活動。在某些情況下，使用者更喜歡直接在文件中執行或（實驗）範例程式碼。（「點擊這裡執行此程式碼。」）

作者應考慮描述範例程式碼的預期輸出或結果，特別是對於難以執行的範例程式碼。

簡潔

範例程式碼應簡短，只包含基本組件。當一個新手 C 程式設計師想學習如何呼叫 malloc 函式時，給他一個簡短的程式碼片段，而不是整個 Linux 原始碼樹。不相關的程式碼可能會分散讀者的注意力並使他們感到困惑。話雖如此，切勿為了簡潔而使用不良實踐；始終將正確性置於簡潔之上。

易於理解

遵循以下建議以建立清晰的範例程式碼：

• 選擇描述性的類別、方法和變數名稱。
• 避免使用難以理解的程式設計技巧來混淆讀者。
• 避免深度巢狀的程式碼。
• 可選：使用粗體或彩色字體來吸引讀者對範例程式碼特定部分的注意力。但是，請謹慎使用高亮顯示——過多的高亮顯示意味著讀者不會專注於任何特定內容。

練習

在以下程式碼片段的註解中，您看到了什麼問題？假設程式碼的目標讀者是剛接觸 br API 但對串流概念有一定經驗的程式設計師：

/* Create a stream from the text file at pathname /tmp/myfile. */
mystream = br.openstream(pathname="/tmp/myfile", mode="z")

點擊圖示查看答案。

註解包含以下缺陷：

• 註解詳細說明了程式碼中相當明顯的部分。
• 程式碼片段沒有解釋程式碼中不明顯的部分。也就是說，mode 參數是什麼，以及 z 值是什麼意思？

註解

考慮以下關於範例程式碼中註解的建議：

• 註解應簡短，但始終將清晰度置於簡潔之上。
• 避免對明顯的程式碼撰寫註解，但請記住，對您（專家）來說明顯的東西，對新手來說可能不明顯。
• 將您的註解精力集中在程式碼中任何不直觀的部分。
• 當您的讀者對某項技術非常有經驗時，不要解釋程式碼在做什麼，而是解釋程式碼為什麼這樣做。

您應該將程式碼的描述放在程式碼註解中還是放在範例程式碼之外的文字（段落或清單）中？請注意，複製貼上程式碼片段的讀者不僅會獲得程式碼，還會獲得任何嵌入的註解。因此，將屬於貼上程式碼的任何描述放入程式碼註解中。相比之下，當您必須解釋一個冗長或棘手的概念時，您通常應該將文字放在範例程式之前。

注意： 如果您必須犧牲生產就緒性以使程式碼更短且更容易理解，請在註解中解釋您的決定。