從實際代碼開始編寫好的示例

當編寫程序時，我花費了大量時間在編寫好的示例上。我從未見過有人寫過關於如何寫出好的示例，所以我就寫了一下如何寫出一份好的示例。

基礎思路就是從你寫的真實代碼開始，然後刪除不相關的細節，使其成為一個獨立的例子，而不是無中生有地想出一些例子。

我將會談論兩種示例：基於真實案例的示例和奇怪的示例

好的示例是真實的

為了說明為什麼好的案例應該是真實的，我們就先討論一個不真實的案例。假設我們在試圖解釋 Python 的 lambda 函數（這只是我想到的第一個概念）。你可以舉一個例子，使用 map 和 lambda 來讓一組數字變為原先的兩倍。

numbers = [1, 2, 3, 4]
squares = map(lambda x: x * x, numbers)

我覺得這個示例不是真實的，有如下兩方面的原因：

• 將一組數字作平方運算不是在真實的程序中完成的事，除非是歐拉項目或某種東西（更多的可能是針對列表的操作）
• map 在 Python 中並不常用，即便是做這個我也更願意寫 [x*x for x in numbers]

一個更加真實的 Python lambdas 的示例是使用 sort 函數，就像這樣：

children = [{"name": "ashwin", "age": 12}, {"name": "radhika", "age": 3}]
sorted_children = sorted(children, key=lambda x: x['age'])

但是這個示例是被精心設計的（為什麼我們需要對這些孩子按照年齡進行排序呢？）。所以我們如何來做一個真實的示例呢？

如何讓你的示例真實起來：看你所寫實際代碼

我認為最簡單的來生成一個例子的方法就是，不是憑空出現一個例子（就像我用那個兒童的例子），而只是從真正的代碼開始！

舉一個例子吧，如果我要用 sort.+key 來編寫一串 Python 代碼，我會發現很多我按某個標準對列表進行排序的真實例子，例如：

• tasks.sort(key=lambda task: task['completed_time'])
• emails = reversed(sorted(emails, key=lambda x:x['receivedAt']))
• sorted_keysizes = sorted(scores.keys(), key=scores.get)
• shows = sorted(dates[date], key=lambda x: x['time']['performanceTime'])

在這裡很容易看到一個規律——這些基本是按時間排序的！因此，你可以明白如何將按時間排序的某些對象（電子郵件、事件等）的簡單實例輕鬆地放在一起。

現實的例子有助於「佈道」你試圖解釋的概念

當我試圖去解釋一個想法（就好比 Python Lambdas）的時候，我通常也會試圖說服讀者，說這是值得學習的想法。Python lambdas 是如此的有用！當我去試圖說服某個人 lambdas 是很好用的時候，讓他想像一下 lambdas 如何幫助他們完成一項他們將要去做的任務或是以及一項他們以前做過的任務，對說服他會很有幫助。

從真實代碼中提煉出示例可能需要很長時間

我給出如何使用 lambda 和 sort 函數的解釋例子是十分簡單的，它並不需要花費我很長時間來想出來，但是將真實的代碼提煉出為一個獨立的示例則是會需要花費很長的時間！

舉個例子，我想在這篇文章中融入一些奇怪的 CSS 行為的例子來說明創造一個奇怪的案例是十分有趣的。我花費了兩個小時來解決我這周遇到的一個實際的問題，確保我理解 CSS 的實際情況，並將其變成一個小示例。

最後，它「僅僅」用了 五行 HTML 和一點點的 CSS 來說明了這個問題，看起來並不想是我花費了好多小時寫出來的。但是最初它卻是幾百行的 JS/CSS/JavaScript，它需要花費很長時間來將所有的代碼化為核心的很少的代碼。

但我認為花點時間把示例講得非常簡單明了是值得的——如果有成百上千的人在讀你的示例，你就節省了他們這麼多時間！

就這麼多了！

我覺得還有更多關於示例可以去講的——幾種不同類型的有用示例，例如：

• 可以更多的改變人的思維而不是直接提供使用的驚喜讀者的示例代碼
• 易於複製粘貼以用作初始化的示例

也許有一天我還會再寫一些呢？ :smiley:

via: https://jvns.ca/blog/2021/07/08/writing-great-examples/

作者：Julia Evans 選題：lujun9972 譯者：zepoch 校對：turbokernel

本文由 LCTT 原創編譯，Linux中國 榮譽推出

本文轉載來自 Linux 中國: https://github.com/Linux-CN/archive