编写代码示例

代码示例是使你的帖子和文章与开发者更相关的原因。它们比关于某个产品的几十页的文章更有意义，而且更重要的是——它们邀请人们去玩你的产品。你甚至可能经常发现自己在看一篇技术文章时直接滚动到第一个代码示例。

事实：像 StackOverflow 这样的平台的成功表明，把解释保持在最低限度，让代码来说话是有意义的。这也产生了一个不幸的影响，许多开发者甚至不再理会代码的"原因"，而是乐于坚持"如何"，并将代码复制和粘贴到他们自己的产品中。我把这些人称为 “FullStackOverflow 开发者”。

用示例来解决问题

我最讨厌的是 “hello world"的例子，它没有做任何有用的事情。相反，我的目标是提供能够解决实际问题的代码。

事实是：“Hello World"代码教人写代码，但不教人如何用它解决问题。

好的代码例子应该回答 “这项技术如何帮助我解决问题？“而不是"我如何使用这个？“的问题。“如何使用这个？“的问题应该由文档来回答。代码实例应该让人们对使用该产品感到兴奋，并吸引他们深入到文档中去了解细节。

因此，与其自己从阅读文档开始，不如检查一下这个工具能做什么，并寻找一个你一直想解决的问题，这个技术可以帮助你。然后用产品来解决它，并以代码为例解释你所做的一切。这也是检查你的产品文档是否有效的一个好方法。如果你作为开发者的代言人被卡住了，而你又找不到有效的文档，这就很好。你有一个最好的例子，说明你可以通过写那个缺失的文档来帮助产品。

展示有效的示例

在一个代码例子中，首先要展示的是一个工作的实现。没有什么比通过点击一个链接或在一个表格中玩一些数据来看看这个东西是怎么做的更有力了。你告诉读者它的工作原理是一回事——读者能够亲自尝试并看到它的工作原理是更有意义的。

提示：如果你解释的代码是一个更大的界面的一部分，在防火墙后面或需要认证，那么你仍然可以通过录制屏幕来展示它是如何工作的。这些影响较小，可能被认为是"假的”，但总比没有好。

例子应该是有效的，但也应该是漂亮和流畅的。很多例子都不能让人满意，或者实际上违反了很多可用性的基本原则——不要给人以低劣的第一印象。

解释必要的环境

你要避免让人们对你的代码感到兴奋，然后无法在他们自己的环境中工作。你可以通过几种方式来解决这个问题：

• 编写防御性的代码：在试图访问它们之前检查依赖性。
• 检查在线和 HTTP 状态：如果你的代码需要从网络服务中提取数据，就说用户需要在线才能运行它。例如，我有过很多抱怨，说我的一些 JavaScript 例子在离线或不运行本地服务器的情况下不能工作。很明显，我没有解释它需要实时数据，而且出于安全考虑，JavaScript 的某些功能只有在通过 HTTPS 访问时才能使用，而不是在文件系统上。
• 列出需要的东西：说说你的依赖性是什么。例如：“需要 Node 和 NPM"或 “在 Microsoft Edge 85 和更新的版本中运行”。如果需要第三方的依赖，为你的读者找到一个好的教程来安装它们，并将依赖的名称链接到它。
• 提供一个简单的测试脚本：检查正确的设置（例子见 test file for GeoMaker ）。
• 为演示提供一个开发者密钥：但要明确告诉人们，要实现你的代码，他们需要一个自己的密钥。提供一个申请密钥的链接。

你无法预测人们在执行你的代码时可能做错的所有事情，但这些是防止挫折的好方法。这使我想到了代码示例的一个重要部分：允许复制和粘贴。

编写有效拷贝和粘贴代码

复制和粘贴可能是最常用的学习代码的方式。你可以把文档写到手指出血，但最大的使用情况是，开发人员会检查一个代码例子，复制并粘贴它，摆弄它，直到他们被卡住，然后开始阅读文档。

事实是：写干净的复制和粘贴的例子是非常重要的。你在代码中添加的任何不好的编码习惯都会被复制并成为实际执行的一部分。

复制和粘贴不起作用的例子不仅没有用，而且对你的声誉也是灾难性的，对实施者来说也是非常令人沮丧的。请确保涵盖以下几点：

• 链接所有资源：将图片、CSS 和脚本资源指向网络位置，而不是将它们链接到本地或相对位置。人们会复制代码并将其粘贴在本地项目中，而不是下载依赖性。
• 提前提供完整的脚本：人们会复制和粘贴大块的脚本，并抱怨它们不起作用，却没有意识到还缺少其他部分。
• 验证和保护你的代码：复制和粘贴的代码需要是优秀的。确保你的代码能与其他代码很好地配合，不会引起任何警告或错误。

可下载的示例

在你的例子中，提供演示代码供下载的 zip 文件应该是你首先做的事情之一。你可以要求读者下载、解压并与你一起编码。这在截屏和视频教程中效果很好。在任何情况下，它都能使你的文章留在读者的脑海中，因为他们的硬盘上有东西提醒他们。

提供你的演示代码的压缩版本可能很烦人，因为每一个变化都意味着你必须重新打包演示。幸运的是，托管代码解决方案，如 GitHub 为您自动完成这项工作。

编写干净、巧妙的示例

我再次强调，你的代码例子应该是你写过的最干净、最聪明的代码。展示一个快速和肮脏的解决方案，让人们开始行动，并为创造最短的代码而立即赢得赞誉，这是非常诱人的。但这是程序员为了给对方留下深刻印象而做的事，而不是开发者布道师所做的事。

你想展示如何用你所布道的产品写出优秀的解决方案，而你所走的每一条捷径都会被复制，并被当作在实际项目中不写优秀代码的借口。这不是我们在这里的目的。

相反，演示代码可以布道最佳的开发实践，并在上下文中展示它们，而不是作为一种学术练习。展示一个通过使用模块模式来保护范围并巧妙地使用闭包的 JavaScript，可以让你与这些想法交叉联系起来，也许能让一些开发者把它们作为他们编码习惯的一部分。

构建代码生成器

为解决方案添加的一个很好的点缀是代码生成器，它允许实施者添加一些参数，点击一个按钮，得到他们想要的代码。这是令人惊讶的强大。

有一个危险是，有些人将永远不会去学习真正的实现技巧。另一方面，这些读者无论如何也不可能这么做。在任何情况下，你会得到更多的人关注这个产品。

托管代码和演示

在个人服务器上托管你的代码和演示可能很诱人，我自己已经这样做了多年。这样做的好处是，你可以控制这个服务器。这样做的坏处是，要由你来维护这个服务器。而你想把你的时间花在布道上，而不是作为一个服务器管理员。

警告：多年来，我一直把我的服务器当作一个游乐场，当我看到它的状态时，这也是痛苦的。我过去的一些代码最后成了极好的攻击载体，有一次我 2006 年的一个 AJAX 演示，最后让一个垃圾博客被安装在一个深藏的文件夹里。这也意味着谷歌封锁了我的域名和许多其他问题。

拥有一个服务器是很好的，但是对于你和看你的代码的人来说，它也应该是很明显的，它是一个划痕板。那里的代码可以而且随时会消失。考虑用一种更加可维护和控制的方式来发布你的演示和代码示例是有意义的。

版本控制

我发现，让我省去很多麻烦的第一件事是对所有东西使用版本控制。Git 是常用的东西，但即使把你的产品放在 OneDrive/Dropbox/Box/Google Drive 或任何文件夹中也是一个好主意。你总是会搞砸的，能够恢复文件的最后一次修改是非常好的。

事实证明，使用 Git 还意味着你可以节省硬盘空间，因为你不会创建名为"test123-safety-still-works"的 Zip 文件，也不会创建每个文件夹都是一个版本名和一个日期的文件夹结构。

使用版本控制系统在过去是令人生畏的，但随着 Git 的出现以及 GitHub 和 Gitlab 等托管解决方案的出现，事情变得简单了。Git 的另一个实际效果是，你不得不对提交的内容进行评论。这样，你就可以创建一个修改历史，用来向潜在的维护者或你想教导的人描述代码。

此外，拥有一个像 GitHub 档案这样的开源托管机构，是让人们找到你的代码实例和课程，为它们做出贡献并给你提供内涵反馈的绝佳方式。在这样的平台上作为问题报告的问题比通过电子邮件或社交媒体平台的随机反馈更容易理解。无论你在哪里安营扎寨，重要的是你不要依赖免费的方案，而是在平台上获得一个更好的、有服务的存在。这些并不昂贵，而且你不希望最终陷入你的代码无法访问的情况，因为你达到了一定的限制或平台改变了。

提示：这是一个重要的观点。你选择的任何平台都应该是一个备份和人们找到你的途径。你不应该把东西寄存在你不能在任何时候得到你所有数据的备份的地方，以便把它转移到其他地方。我们的市场不断变化，所以要确保你不要依赖一个可能很快就会消失的资源，以及你所有的工作。

事实：基于 Git 的代码共享平台在设计上是相互兼容的，所以这一点应该给你一些安全感。这些平台也为服务和提供代码进行了高度优化，就像 YouTube 和类似服务为媒体流进行优化一样。

在向人们讲述代码时，我的一个主要烦恼是，你的教程和文档中需要有可执行的代码和可读的代码。我花了好几年的时间来改变那些运行良好的代码，使其在博客平台和书籍中正确显示。通过在这样的平台上托管你的例子，这根本就不是一个问题。

自动托管

代码托管平台不仅允许你存储你的代码，并使人们能够访问它。这些平台也有内置的反馈机制，人们可以拿着你的代码，拿着一份拷贝，并在那里按照他们的需要进行修改。

对你来说，也可以选择添加维基和文档。更重要的是，这些平台中的大多数不仅允许你托管你的代码，而且还允许你执行它。这自然会有一些限制。你几乎可以在这些平台中的任何一个显示 HTML、CSS 和 JavaScript。服务器端的可执行代码更难找到地方托管，但也有一些平台允许完整的应用程序与源代码一起托管。

大多数平台都会包含一些静态网站生成工具，如 Gatsby、Jekyll 或类似的工具。如果你是在网上阅读这本书，这就是我使用的。这里的文本是用 markdown 写的，我是用 GitHub pages 和 Jekyll 来生成 HTML。

代码沙箱

除了用于托管你的代码和产品的平台外，还有一些代码沙箱服务可用。这些服务允许你写一个代码示例，并与世界分享源代码和可执行性。这些平台是编辑器和看到结果的地方，并为这种使用情况进行了高度优化。作为额外的奖励，它们还允许你在博客文章和文章中嵌入代码示例。

JSFiddle 是最早的一个，后来在 JSBin 起飞，并且 Codepen 是这个领域的另一个大玩家。它们不仅允许你编写基本的网络代码，而且还为你提供预编译器，这样你就可以集中精力向人们展示某个抽象概念的工作原理，而不必通过设置和定制抽象库来说服他们。当我在 Mozilla 网络文档团队工作时，我们发现人们在解释的地方直接尝试代码是一个很大的胜利。

在培训过程中，你可能会遇到这样的情况：由于公司的政策，他们的电脑无法安装任何软件。通过使用这些服务，你仍然可以运行你的课程，因为与会者需要的只是一个浏览器和一个连接。

实时编码环境

这些平台中的许多也有演示和现场模式，允许你与其他人实时开发，就像你可以使用 Office 365 和 Google Docs 来协作编写文本。Code Sandbox、Glitch 和许多其他的平台都擅长于此，Codepen 和 JSBin 也都升级了他们的功能集，以适应这种使用情况。

现场编码环境对于向考虑预订你的 workshop 或演讲的潜在客户展示一些东西是非常好的。它们也是创建一个简单的用例，并与世界上任何地方的团队一起解决一个问题的极好方法。毫不奇怪，它们也经常在面试中使用。

代码展示

其中一些平台在围绕代码实例建立社区方面做得很好。例如，Codepen 是一个寻找实例的宝库，可以将其添加到你的演讲中，并解释是什么技术促成了它们。不过，重要的是，要把功劳归功于人。你也可以参与其中，并通过在那里展示很酷的东西来为自己赢得声誉。

通常这些例子玩的是最新的技术，是你作为开发者布道师向潜在的其他用户展示其价值的好方法。而且，毕竟，他们玩起来很有趣。我发现有不少有趣的人通过展示网站来分享信息，有些演示在使我工作的浏览器表现得更好方面发挥了作用，因为它们对渲染引擎有一定的负担。