我們喜歡在Big Nerd Ranch上教點(diǎn)東西，但我們所做的可不只是上課而已。在那之外，我們也得寫(xiě)點(diǎn)博客，或在一些會(huì)議上演講。在這些活動(dòng)中，我們時(shí)常會(huì)有想跟大家分享代碼的沖動(dòng)。而很多時(shí)候，最佳的分享途徑就是demo的展示。

如何制作出最有用的demo呢？我們?cè)谶@里（非正式地）提出了一些建議。

共情

共情是所有這些建議的基礎(chǔ)。教學(xué)的時(shí)候，我們要努力在學(xué)生的角度換位思考。我們要記得學(xué)習(xí)新知識(shí)的感覺(jué)，尤其是當(dāng)新知識(shí)是以實(shí)例展現(xiàn)的時(shí)候。我們要記得哪些demo曾對(duì)我們有過(guò)幫助。我們還要記住，有些demo在學(xué)習(xí)中其實(shí)是起反作用的。

簡(jiǎn)，易

在demo中，我們要專(zhuān)注于單一的主題。我們的教學(xué)覆蓋了很大的知識(shí)范圍，因此，化整為零是非常必要的。

例如，我們要說(shuō)明Android或iOS中的一個(gè)新特性，那只講這一個(gè)話題就好了。別跟我說(shuō)你的demo能“以一敵三”——既展示Material design中最新的UI元素，又介紹RecyclerView，同時(shí)還討論RxJava的新特性。要真這樣，那我也是醉了。真想好好講上面這些知識(shí)的話，那你就應(yīng)該為每個(gè)知識(shí)點(diǎn)分別寫(xiě)demo。

低估聽(tīng)眾

學(xué)生的水平良莠不齊。某個(gè)學(xué)生可能有10年開(kāi)發(fā)經(jīng)驗(yàn)，但另一個(gè)可能只接觸了1年。

制作demo時(shí)，我們很多時(shí)候會(huì)過(guò)度低估聽(tīng)眾的經(jīng)驗(yàn)水平，盡力做到詳盡清晰。然而，我們的目標(biāo)是幫助更多有經(jīng)驗(yàn)的開(kāi)發(fā)者從demo中獲益。

非核心，莫求新

我們的大腦很擅長(zhǎng)挑選新知識(shí)而忽略舊事物。讀代碼時(shí)尤其如此。

在訓(xùn)練營(yíng)講新話題時(shí)，我們希望與話題高度相關(guān)的代碼能夠足夠醒目。要做到這一點(diǎn)，一個(gè)辦法就是依靠人們最熟悉的代碼，讓所有非必要的部分“消失”。

例如，我們展示RxJava中的新特性，建立了一個(gè)虛擬的片段和視圖來(lái)讓結(jié)果可視化。如果我們使用額外的高級(jí)方法，例如為widget使用Butterknife注釋?zhuān)潜貙⑿e奪主，RxJava的相關(guān)細(xì)節(jié)無(wú)法得到突出。那些不熟悉Butterknife的人就會(huì)分散注意力，開(kāi)始疑惑：“這是什么鬼？這跟Rxjava有何相關(guān)之處？”

我們應(yīng)該堅(jiān)持使用守舊卻好用的findViewById()，而不是搞一大堆無(wú)關(guān)信息出來(lái)。這樣，學(xué)生會(huì)看到findviewbyid()，認(rèn)出這是個(gè)熟悉的東西，然后忽略它。他們就可以繼續(xù)往下搜尋陌生的代碼了。

反常規(guī)處多說(shuō)明

你的demo不可能盡善盡美。你必須得抄點(diǎn)近路，建立一些框架用以輔助展示你的主題。Demo和真正的應(yīng)用不同；“抄近路”不失為好的選擇。每當(dāng)“抄近路”或做一些不該做的事情的時(shí)候，你一定要確保跟別人講清楚自己在做什么。若不這樣做，你面臨兩個(gè)風(fēng)險(xiǎn)：

• 經(jīng)驗(yàn)豐富的開(kāi)發(fā)者會(huì)看到你代碼不對(duì)勁，從而對(duì)你失去信任。他們會(huì)一直存有疑慮，當(dāng)你開(kāi)始認(rèn)真展示demo的核心部分時(shí)，很難轉(zhuǎn)而讓他們信服。如果在建立提供虛擬后臺(tái)數(shù)據(jù)的模型存儲(chǔ)時(shí)搞不好，那你何以說(shuō)服別人面對(duì)實(shí)際問(wèn)題時(shí)能做好呢？你得跟那些有經(jīng)驗(yàn)的人說(shuō)清楚，讓他們知道自己是在有意識(shí)地“抄近路”。
• 你不希望demo中不完善的方案被新手實(shí)際拿去用。新手可能會(huì)檢查你的代碼，看到它技術(shù)上運(yùn)行沒(méi)問(wèn)題，就直接把它移植到自己的項(xiàng)目中去了。我們要努力成為好的老師，確保學(xué)生不要養(yǎng)成任何壞習(xí)慣。

Readme > Javadoc

正式的應(yīng)用與demo要有不同的文檔技術(shù)和庫(kù)，它們分別面向不同的聽(tīng)眾。GitHub很擅長(zhǎng)把README.md文件格式化，從而達(dá)到更好的閱讀效果。它可以很好地展示demo的內(nèi)容。通過(guò)它，我們可以高度概括地向聽(tīng)眾說(shuō)明我們所要展示的東西。 截圖、Gif動(dòng)畫(huà)和詳細(xì)的安裝說(shuō)明，這些都很有價(jià)值。好好利用它們。

當(dāng)你知道自己在找什么的時(shí)候，Javadoc是很好用的。但對(duì)于學(xué)新東西的人而言，它們不啻洪水猛獸。你要寫(xiě)的文檔不是開(kāi)發(fā)者日常所用API的文檔。讓文檔更通俗一點(diǎn)，這會(huì)好很多。

不吝注釋?zhuān)?/h2>

在正式項(xiàng)目中，我們可以在注釋多寡間找到一個(gè)平衡。實(shí)際中，你面臨著注釋與代碼脫節(jié)的風(fēng)險(xiǎn)，可能導(dǎo)致團(tuán)隊(duì)重構(gòu)。然而，demo項(xiàng)目通常很少更新，所以這倒不是個(gè)大問(wèn)題。記住，你是在向別人解釋新知識(shí)。帶領(lǐng)學(xué)生逐行分析代碼會(huì)非常有效。

實(shí)際項(xiàng)目中，開(kāi)發(fā)者在閱讀和理解代碼時(shí)有很多上下文能幫忙。對(duì)于代碼應(yīng)該是什么樣，他們心中可能已經(jīng)高度有數(shù)了。他們還可能聽(tīng)其他同事談?wù)撨^(guò)這些代碼所要解決的問(wèn)題。甚至在這些代碼所依賴(lài)的設(shè)計(jì)方面，團(tuán)隊(duì)可能已經(jīng)取得了一致。這些項(xiàng)目的注釋跟我們的有完全不同的目的。它們提供簡(jiǎn)單、高層次的指導(dǎo)。

而對(duì)于第一次看到demo項(xiàng)目的開(kāi)發(fā)者而言，他們沒(méi)有上下文能幫助理解。無(wú)論是項(xiàng)目本身，還是項(xiàng)目中展示的技術(shù)和庫(kù)，對(duì)他們而言都是嶄新的。因此，我們有必要用大量注釋來(lái)讓邏輯和流程更加清晰。

拿出來(lái)遛遛

有些demo只有與之互動(dòng)才能充分理解，僅僅看代碼則難以咀嚼。如果你的demo是前者，一定要把它給大家實(shí)際用一下。編譯項(xiàng)目，把它們放在Google Play或Apple Store上，然后在你的README里將其鏈接好。

因?yàn)閷W(xué)生不可能花時(shí)間去復(fù)制你的repo、導(dǎo)入到IDE、再編譯并部署到本地設(shè)備上。你應(yīng)該讓大家盡量容易和快速地開(kāi)始互動(dòng)。

這都是好的demo所必要的技術(shù)。你想在一個(gè)好的demo中看到哪些東西呢？請(qǐng)告知我們，或把你喜歡的demo的鏈接發(fā)出來(lái)吧。

英文原文：How to Write Great Demo Apps

作者：南羽語(yǔ)玉

來(lái)源：http://www.jianshu.com/p/9486dab476e5