建立範例程式碼

預估時間： 10 分鐘

好的範例程式碼往往是最好的文件。即使你的段落和清單寫得再清楚，程式設計師仍然偏好優質的範例程式碼。畢竟，文字和程式碼是不同的語言，而讀者真正關心的是程式碼本身。試著用文字解釋程式碼，就像用英文解釋一首義大利詩一樣困難。

好的範例程式碼應該是正確且簡潔的，讓讀者能夠快速理解、輕鬆重複使用，且帶來的副作用最小。

正確

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

• 能夠正確編譯，不產生錯誤。
• 能執行其宣稱要完成的任務。
• 盡可能達到生產環境可用的水準（production-ready），例如程式碼不應有安全漏洞。
• 遵循語言特有的慣例。

範例程式碼是直接影響使用者如何寫程式的機會。因此，範例程式碼應該展示使用產品的最佳方式。如果針對同一任務有多種寫法，請以團隊共同決定的最佳方法來撰寫。如果團隊尚未討論過各種方法的優缺點，建議花時間進行評估。

一定要測試你的範例程式碼。隨著時間推移，系統會變動，範例程式碼可能會失效。請準備像維護其他程式碼那樣維護範例程式碼。

許多團隊會重複使用單元測試作為範例程式，這有時並非好主意。單元測試的主要目標是測試；而範例程式碼的唯一目標是教學。

程式碼片段（snippet） 是範例程式碼中的一小段，可能只有一行或幾行。大量使用 snippet 的文件通常會隨著時間腐敗，因為團隊往往不會像測試完整範例程式那樣嚴格測試 snippets。

執行範例程式碼

好的文件會說明如何執行範例程式碼。例如，文件可能需要告訴使用者在執行範例之前，先完成以下操作：

• 安裝某個函式庫。
• 調整特定環境變數的值。
• 在整合開發環境（IDE）中進行相關設定。

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

文件作者應考慮描述範例程式碼的預期輸出或結果，尤其是那些不易執行的範例。

簡潔

範例程式碼應該簡短，只包含必要的部分。當一位初學 C 語言的程式設計師想學習如何呼叫 malloc 函式時，給他一段簡短的程式碼片段就好，而不是整個 Linux 原始碼。無關的程式碼會令讀者分散注意力並產生困惑。不過，千萬不要為了簡短而採用不好的寫法；正確永遠比簡潔更重要。

易懂

請遵循以下建議來撰寫清晰的範例程式碼：

• 選擇具描述性的類別、方法和變數名稱。
• 避免用難以理解的程式技巧來混淆讀者。
• 避免過度巢狀的程式碼。
• （非必要）使用粗體或彩色字體來吸引讀者注意範例程式碼中的特定區域。但請謹慎使用強調效果——過多強調反而會讓讀者無法專注於任何特定內容。

練習

以下哪一行程式碼對於剛接觸 go.so API 的軟體工程師來說更有幫助？

1. MyLevel = go.so.Level(5, 28, 48)
2. MyLevel = go.so.Level(rank=5, 28, 48)
3. MyLevel = go.so.Level(rank=5, dimension=28, opacity=48)

註解

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

• 註解要簡短，但始終以清晰優先於簡潔。
• 避免為直白的程式碼寫註解，但請記住，你（專家）覺得顯而易見的事，對新手來說可能並不明顯。
• 把撰寫註解的心力放在那些不直觀的程式碼上。
• 當讀者對某項技術非常熟悉時，不要解釋程式碼「在做什麼」，而是解釋「為什麼這麼做」。

程式碼的說明應該要放在程式碼註解中，還是放在程式碼外的文字區塊（段落或清單）？請注意，讀者在複製貼上程式碼片段時，不僅會複製程式碼，也會複製其中的註解。所以，任何需要在貼上程式碼時一併出現的說明都應該寫在程式註解裡。相反地，當你必須解釋冗長或複雜的概念時，通常應將說明文字放在範例程式碼之前。

注意： 如果你打算犧牲生產環境的完成度來讓程式碼更簡短且易於理解，請在註解中說明你的考量。

練習

以下程式碼片段中的註解有哪些問題？假設程式碼是給剛接觸 br API，但已有串流概念的程式設計師看的：

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

可重複使用

為了讓讀者能輕鬆重複使用您的範例程式碼，請提供以下內容：

• 執行範例程式碼所需的所有資訊，包括相依性與設定步驟。
• 具有可擴充或可客製化功能的程式碼。

擁有簡潔、易懂且能通過編譯的範例程式碼是個好開始，但如果程式碼會導致讀者的應用程式崩潰，讀者肯定不會開心。因此，撰寫範例程式碼時，請考慮你的程式碼整合到其他程式中可能產生的任何副作用。沒有人想要不安全或極度低效率的程式碼。

範例與反例

除了告訴讀者「該怎麼做」之外，有時也應該示範「不該怎麼做」。例如，許多程式語言允許程式設計師在等號兩邊放置空白，但如果你正在寫的語法教學文件是類似 bash 這種不允許等號兩邊有空白的語言，此時同時展示正確與錯誤的範例對讀者會很有幫助。例如：

# 合法的字串賦值。
s="The rain in Maine."

# 因為等號兩邊有空白，這是不合法的字串賦值。
s = "The rain in Maine."

程式碼範例的順序

一組好的範例程式碼應該展示不同層次的複雜度。

對某項技術完全陌生的讀者，通常渴望簡單的入門範例。範例程式碼組合中的第一個、且最基本的範例通常稱為 Hello World 程式。掌握基礎後，工程師會想要更複雜的範例。一組好的範例程式會涵蓋簡單、中等和複雜的程式範例。

練習

以下哪一組範例函式最適合用於教導新手函式概念的教學？

1. 以下函式組合：
   1. 一個不帶參數且不回傳任何值的函式。
   2. 一個帶有一個參數但不回傳任何值的函式。
   3. 一個接受一個參數並返回一個值的函式。
   4. 一個接受三個參數並返回一個值的函式。
2. 以下函式組合：
   1. 一個接受三個參數並返回一個值的函式。
3. 以下函式組合：
   1. 一個接受一個參數並返回一個值的函式。
   2. 一個接受三個參數並返回一個值的函式。

下一步？

恭喜你完成《技術寫作二》的課前研讀。

如果你的組織有開設《技術寫作二》的實體課程，請務必參加。如果你想協助帶領這門課，請參考講師指南。

《技術寫作二》課程所有主題的重點都已彙整在總結頁面。