作者：Christian Heilmann
编译：庄七
代碼示例是使你的帖子和文章與開發者更相關的原因。它們比關於某個產品的幾十頁的文章更有意義，而且更重要的是——它們邀請人們去玩你的產品。你甚至可能經常發現自己在看一篇技術文章時直接滾動到第一個代碼示例。
事實：像 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 是一個尋找實例的寶庫，可以將其添加到你的演講中，並解釋是什麼技術促成了它們。不過，重要的是，要把功勞歸於人。你也可以參與其中，並通過在那裡展示很酷的東西來為自己贏得聲譽。
通常這些例子玩的是最新的技術，是你作為開發者布道師向潛在的其他用戶展示其價值的好方法。而且，畢竟，他們玩起來很有趣。我發現有不少有趣的人通過展示網站來分享信息，有些演示在使我工作的瀏覽器表現得更好方面發揮了作用，因為它們對渲染引擎有一定的負擔。
轉載請註明：開發者關係 »
