從實(shí)際代碼開(kāi)始編寫(xiě)好的示例
當(dāng)編寫(xiě)程序時(shí)，我花費(fèi)了大量時(shí)間在編寫(xiě)好的示例上。我從未見(jiàn)過(guò)有人寫(xiě)過(guò)關(guān)于如何寫(xiě)出好的示例，所以我就寫(xiě)了一下如何寫(xiě)出一份好的示例。
基礎(chǔ)思路就是從你寫(xiě)的真實(shí)代碼開(kāi)始，然后刪除不相關(guān)的細(xì)節(jié)，使其成為一個(gè)獨(dú)立的例子，而不是無(wú)中生有地想出一些例子。
我將會(huì)談?wù)搩煞N示例：基于真實(shí)案例的示例和奇怪的示例
好的示例是真實(shí)的
為了說(shuō)明為什么好的案例應(yīng)該是真實(shí)的，我們就先討論一個(gè)不真實(shí)的案例。假設(shè)我們?cè)谠噲D解釋 Python 的 lambda 函數(shù)（這只是我想到的第一個(gè)概念）。你可以舉一個(gè)例子，使用 map 和 lambda 來(lái)讓一組數(shù)字變?yōu)樵鹊膬杀丁?/p>
numbers = [1, 2, 3, 4]squares = map(lambda x: x * x, numbers)
我覺(jué)得這個(gè)示例不是真實(shí)的，有如下兩方面的原因：
- 將一組數(shù)字作平方運(yùn)算不是在真實(shí)的程序中完成的事，除非是歐拉項(xiàng)目或某種東西（更多的可能是針對(duì)列表的操作）
map在 Python 中并不常用，即便是做這個(gè)我也更愿意寫(xiě)[x*x for x in numbers]
一個(gè)更加真實(shí)的 Python lambdas 的示例是使用 sort 函數(shù)，就像這樣：
children = [{"name": "ashwin", "age": 12}, {"name": "radhika", "age": 3}]sorted_children = sorted(children, key=lambda x: x['age'])
但是這個(gè)示例是被精心設(shè)計(jì)的（為什么我們需要對(duì)這些孩子按照年齡進(jìn)行排序呢？）。所以我們?nèi)绾蝸?lái)做一個(gè)真實(shí)的示例呢？
如何讓你的示例真實(shí)起來(lái)：看你所寫(xiě)實(shí)際代碼
我認(rèn)為最簡(jiǎn)單的來(lái)生成一個(gè)例子的方法就是，不是憑空出現(xiàn)一個(gè)例子（就像我用那個(gè)兒童的例子），而只是從真正的代碼開(kāi)始！
舉一個(gè)例子吧，如果我要用 sort.+key 來(lái)編寫(xiě)一串 Python 代碼，我會(huì)發(fā)現(xiàn)很多我按某個(gè)標(biāo)準(zhǔn)對(duì)列表進(jìn)行排序的真實(shí)例子，例如：
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'])
在這里很容易看到一個(gè)規(guī)律——這些基本是按時(shí)間排序的！因此，你可以明白如何將按時(shí)間排序的某些對(duì)象（電子郵件、事件等）的簡(jiǎn)單實(shí)例輕松地放在一起。
現(xiàn)實(shí)的例子有助于“布道”你試圖解釋的概念
當(dāng)我試圖去解釋一個(gè)想法（就好比 Python Lambdas）的時(shí)候，我通常也會(huì)試圖說(shuō)服讀者，說(shuō)這是值得學(xué)習(xí)的想法。Python lambdas 是如此的有用！當(dāng)我去試圖說(shuō)服某個(gè)人 lambdas 是很好用的時(shí)候，讓他想象一下 lambdas 如何幫助他們完成一項(xiàng)他們將要去做的任務(wù)或是以及一項(xiàng)他們以前做過(guò)的任務(wù)，對(duì)說(shuō)服他會(huì)很有幫助。
從真實(shí)代碼中提煉出示例可能需要很長(zhǎng)時(shí)間
我給出如何使用 lambda 和 sort 函數(shù)的解釋例子是十分簡(jiǎn)單的，它并不需要花費(fèi)我很長(zhǎng)時(shí)間來(lái)想出來(lái)，但是將真實(shí)的代碼提煉出為一個(gè)獨(dú)立的示例則是會(huì)需要花費(fèi)很長(zhǎng)的時(shí)間！
舉個(gè)例子，我想在這篇文章中融入一些奇怪的 CSS 行為的例子來(lái)說(shuō)明創(chuàng)造一個(gè)奇怪的案例是十分有趣的。我花費(fèi)了兩個(gè)小時(shí)來(lái)解決我這周遇到的一個(gè)實(shí)際的問(wèn)題，確保我理解 CSS 的實(shí)際情況，并將其變成一個(gè)小示例。
最后，它“僅僅”用了 五行 HTML 和一點(diǎn)點(diǎn)的 CSS 來(lái)說(shuō)明了這個(gè)問(wèn)題，看起來(lái)并不想是我花費(fèi)了好多小時(shí)寫(xiě)出來(lái)的。但是最初它卻是幾百行的 JS/CSS/JavaScript，它需要花費(fèi)很長(zhǎng)時(shí)間來(lái)將所有的代碼化為核心的很少的代碼。
但我認(rèn)為花點(diǎn)時(shí)間把示例講得非常簡(jiǎn)單明了是值得的——如果有成百上千的人在讀你的示例，你就節(jié)省了他們這么多時(shí)間！
就這么多了！
我覺(jué)得還有更多關(guān)于示例可以去講的——幾種不同類(lèi)型的有用示例，例如：
- 可以更多的改變?nèi)说乃季S而不是直接提供使用的驚喜讀者的示例代碼
- 易于復(fù)制粘貼以用作初始化的示例
也許有一天我還會(huì)再寫(xiě)一些呢？ :smiley:
