建立範例程式碼
預估時間: 10 分鐘
好的範例程式碼往往是最好的文件。即使你的段落和清單寫得再清楚,程式設計師仍然偏好優質的範例程式碼。畢竟,文字和程式碼是不同的語言,而讀者真正關心的是程式碼本身。試著用文字解釋程式碼,就像用英文解釋一首義大利詩一樣困難。
好的範例程式碼應該是正確且簡潔的,讓讀者能夠快速理解、輕鬆重複使用,且帶來的副作用最小。
正確
範例程式碼應符合以下標準:
- 能夠正確編譯,不產生錯誤。
- 能執行其宣稱要完成的任務。
- 盡可能達到生產環境可用的水準(production-ready),例如程式碼不應有安全漏洞。
- 遵循語言特有的慣例。
範例程式碼是直接影響使用者如何寫程式的機會。因此,範例程式碼應該展示使用產品的最佳方式。如果針對同一任務有多種寫法,請以團隊共同決定的最佳方法來撰寫。如果團隊尚未討論過各種方法的優缺點,建議花時間進行評估。
一定要測試你的範例程式碼。隨著時間推移,系統會變動,範例程式碼可能會失效。請準備像維護其他程式碼那樣維護範例程式碼。
許多團隊會重複使用單元測試作為範例程式,這有時並非好主意。單元測試的主要目標是測試;而範例程式碼的唯一目標是教學。
程式碼片段(snippet) 是範例程式碼中的一小段,可能只有一行或幾行。大量使用 snippet 的文件通常會隨著時間腐敗,因為團隊往往不會像測試完整範例程式那樣嚴格測試 snippets。
執行範例程式碼
好的文件會說明如何執行範例程式碼。例如,文件可能需要告訴使用者在執行範例之前,先完成以下操作:
- 安裝某個函式庫。
- 調整特定環境變數的值。
- 在整合開發環境(IDE)中進行相關設定。
使用者不一定都能正確執行上述步驟。在某些情況下,使用者更喜歡直接在文件中執行(或實驗)範例程式碼(「點這裡執行程式碼」)。
文件作者應考慮描述範例程式碼的預期輸出或結果,尤其是那些不易執行的範例。
簡潔
範例程式碼應該簡短,只包含必要的部分。當一位初學 C 語言的程式設計師想學習如何呼叫 malloc
函式時,給他一段簡短的程式碼片段就好,而不是整個 Linux 原始碼。無關的程式碼會令讀者分散注意力並產生困惑。不過,千萬不要為了簡短而採用不好的寫法;正確永遠比簡潔更重要。
易懂
請遵循以下建議來撰寫清晰的範例程式碼:
- 選擇具描述性的類別、方法和變數名稱。
- 避免用難以理解的程式技巧來混淆讀者。
- 避免過度巢狀的程式碼。
- (非必要)使用粗體或彩色字體來吸引讀者注意範例程式碼中的特定區域。但請謹慎使用強調效果——過多強調反而會讓讀者無法專注於任何特定內容。
關於在文件中加入強調效果,有一句話是這麼說的:「到處都畫重點,就等於沒有重點。」
練習
以下哪一行程式碼對於剛接觸 go.so
API 的軟體工程師來說更有幫助?
MyLevel = go.so.Level(5, 28, 48)
MyLevel = go.so.Level(rank=5, 28, 48)
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")
此註解有以下缺點:
- 註解詳細說明了程式碼中相當直觀的部分。
- 此程式碼片段並未解釋不直觀的部分。也就是說,
mode
參數是什麼,以及參數值為z
意味著什麼?
可重複使用
為了讓讀者能輕鬆重複使用您的範例程式碼,請提供以下內容:
- 執行範例程式碼所需的所有資訊,包括相依性與設定步驟。
- 具有可擴充或可客製化功能的程式碼。
擁有簡潔、易懂且能通過編譯的範例程式碼是個好開始,但如果程式碼會導致讀者的應用程式崩潰,讀者肯定不會開心。因此,撰寫範例程式碼時,請考慮你的程式碼整合到其他程式中可能產生的任何副作用。沒有人想要不安全或極度低效率的程式碼。
範例與反例
除了告訴讀者「該怎麼做」之外,有時也應該示範「不該怎麼做」。例如,許多程式語言允許程式設計師在等號兩邊放置空白,但如果你正在寫的語法教學文件是類似 bash 這種不允許等號兩邊有空白的語言,此時同時展示正確與錯誤的範例對讀者會很有幫助。例如:
# 合法的字串賦值。
s="The rain in Maine."
# 因為等號兩邊有空白,這是不合法的字串賦值。
s = "The rain in Maine."
程式碼範例的順序
一組好的範例程式碼應該展示不同層次的複雜度。
對某項技術完全陌生的讀者,通常渴望簡單的入門範例。範例程式碼組合中的第一個、且最基本的範例通常稱為 Hello World 程式。掌握基礎後,工程師會想要更複雜的範例。一組好的範例程式會涵蓋簡單、中等和複雜的程式範例。
練習
以下哪一組範例函式最適合用於教導新手函式概念的教學?
- 以下函式組合:
- 一個不帶參數且不回傳任何值的函式。
- 一個帶有一個參數但不回傳任何值的函式。
- 一個接受一個參數並返回一個值的函式。
- 一個接受三個參數並返回一個值的函式。
- 以下函式組合:
- 一個接受三個參數並返回一個值的函式。
- 以下函式組合:
- 一個接受一個參數並返回一個值的函式。
- 一個接受三個參數並返回一個值的函式。
下一步?
恭喜你完成《技術寫作二》的課前研讀。
如果你的組織有開設《技術寫作二》的實體課程,請務必參加。如果你想協助帶領這門課,請參考講師指南。
《技術寫作二》課程所有主題的重點都已彙整在總結頁面。