我们喜欢在Big Nerd Ranch上教点东西，但我们所做的可不只是上课而已。在那之外，我们也得写点博客，或在一些会议上演讲。在这些活动中，我们时常会有想跟大家分享代码的冲动。而很多时候，最佳的分享途径就是demo的展示。

如何制作出最有用的demo呢？我们在这里（非正式地）提出了一些建议。

共情

共情是所有这些建议的基础。教学的时候，我们要努力在学生的角度换位思考。我们要记得学习新知识的感觉，尤其是当新知识是以实例展现的时候。我们要记得哪些demo曾对我们有过帮助。我们还要记住，有些demo在学习中其实是起反作用的。

简，易

在demo中，我们要专注于单一的主题。我们的教学覆盖了很大的知识范围，因此，化整为零是非常必要的。

例如，我们要说明Android或iOS中的一个新特性，那只讲这一个话题就好了。别跟我说你的demo能“以一敌三”——既展示Material design中最新的UI元素，又介绍RecyclerView，同时还讨论RxJava的新特性。要真这样，那我也是醉了。真想好好讲上面这些知识的话，那你就应该为每个知识点分别写demo。

低估听众

学生的水平良莠不齐。某个学生可能有10年开发经验，但另一个可能只接触了1年。

制作demo时，我们很多时候会过度低估听众的经验水平，尽力做到详尽清晰。然而，我们的目标是帮助更多有经验的开发者从demo中获益。

非核心，莫求新

我们的大脑很擅长挑选新知识而忽略旧事物。读代码时尤其如此。

在训练营讲新话题时，我们希望与话题高度相关的代码能够足够醒目。要做到这一点，一个办法就是依靠人们最熟悉的代码，让所有非必要的部分“消失”。

例如，我们展示RxJava中的新特性，建立了一个虚拟的片段和视图来让结果可视化。如果我们使用额外的高级方法，例如为widget使用Butterknife注释，那必将喧宾夺主，RxJava的相关细节无法得到突出。那些不熟悉Butterknife的人就会分散注意力，开始疑惑：“这是什么鬼？这跟Rxjava有何相关之处？”

我们应该坚持使用守旧却好用的findViewById()，而不是搞一大堆无关信息出来。这样，学生会看到findviewbyid()，认出这是个熟悉的东西，然后忽略它。他们就可以继续往下搜寻陌生的代码了。

反常规处多说明

你的demo不可能尽善尽美。你必须得抄点近路，建立一些框架用以辅助展示你的主题。Demo和真正的应用不同；“抄近路”不失为好的选择。每当“抄近路”或做一些不该做的事情的时候，你一定要确保跟别人讲清楚自己在做什么。若不这样做，你面临两个风险：

• 经验丰富的开发者会看到你代码不对劲，从而对你失去信任。他们会一直存有疑虑，当你开始认真展示demo的核心部分时，很难转而让他们信服。如果在建立提供虚拟后台数据的模型存储时搞不好，那你何以说服别人面对实际问题时能做好呢？你得跟那些有经验的人说清楚，让他们知道自己是在有意识地“抄近路”。
• 你不希望demo中不完善的方案被新手实际拿去用。新手可能会检查你的代码，看到它技术上运行没问题，就直接把它移植到自己的项目中去了。我们要努力成为好的老师，确保学生不要养成任何坏习惯。

Readme > Javadoc

正式的应用与demo要有不同的文档技术和库，它们分别面向不同的听众。GitHub很擅长把README.md文件格式化，从而达到更好的阅读效果。它可以很好地展示demo的内容。通过它，我们可以高度概括地向听众说明我们所要展示的东西。 截图、Gif动画和详细的安装说明，这些都很有价值。好好利用它们。

当你知道自己在找什么的时候，Javadoc是很好用的。但对于学新东西的人而言，它们不啻洪水猛兽。你要写的文档不是开发者日常所用API的文档。让文档更通俗一点，这会好很多。

不吝注释！

在正式项目中，我们可以在注释多寡间找到一个平衡。实际中，你面临着注释与代码脱节的风险，可能导致团队重构。然而，demo项目通常很少更新，所以这倒不是个大问题。记住，你是在向别人解释新知识。带领学生逐行分析代码会非常有效。

实际项目中，开发者在阅读和理解代码时有很多上下文能帮忙。对于代码应该是什么样，他们心中可能已经高度有数了。他们还可能听其他同事谈论过这些代码所要解决的问题。甚至在这些代码所依赖的设计方面，团队可能已经取得了一致。这些项目的注释跟我们的有完全不同的目的。它们提供简单、高层次的指导。

而对于第一次看到demo项目的开发者而言，他们没有上下文能帮助理解。无论是项目本身，还是项目中展示的技术和库，对他们而言都是崭新的。因此，我们有必要用大量注释来让逻辑和流程更加清晰。

拿出来遛遛

有些demo只有与之互动才能充分理解，仅仅看代码则难以咀嚼。如果你的demo是前者，一定要把它给大家实际用一下。编译项目，把它们放在Google Play或Apple Store上，然后在你的README里将其链接好。

因为学生不可能花时间去复制你的repo、导入到IDE、再编译并部署到本地设备上。你应该让大家尽量容易和快速地开始互动。

这都是好的demo所必要的技术。你想在一个好的demo中看到哪些东西呢？请告知我们，或把你喜欢的demo的链接发出来吧。

英文原文：How to Write Great Demo Apps

作者：南羽语玉

来源：http://www.jianshu.com/p/9486dab476e5