【文章內容使用 Gemini 1.5 Pro 自動產生】
寫一個好的程式碼範例
撰寫好的程式碼範例很難。讓我說明一下，製作一個範例來演示 API 的用法或展示 UI 慣用語可能很快且容易。難度來自於你需要添加到你的儲存庫中的額外部分，以保持程式碼範例新鮮並吸引你的開發人員。
首先，你需要在你的程式碼中添加一個好的 README，從一個摘要開始，說明開發人員為什麼應該投入時間和精力來研究和理解這個範例。接著，提供使用說明和連結到問題追蹤器，開發人員可以在其中提出錯誤並要求澄清，如果遇到令人困惑的部分。
接下來是程式碼本身。程式碼是否遵循佈局和使用的慣例？這可能像程式碼放在哪裡一樣簡單，也可能像 linter 等適當的設定一樣複雜。我喜歡已經採用了強大的程式碼格式、佈局和 linting 規則集標準的程式設計社群語言。這些標準使程式碼的外觀保持一致，從而更容易導航。若要強制執行 Dart 和 Flutter 的程式碼格式，你可以將以下命令添加到你的 CI 管線，如果格式不正確，則會使構建失敗：
1 | $ dart format --output none --set-exit-if-changed . |
在程式碼格式化後，下一步是強制執行一套好的 lints。對於 Dart，我強烈建議研究 lints 套件，對於 Flutter，我同樣建議研究 flutter_lints 套件。若要確保 lints 在 CI 管線中通過，請添加以下命令：
1 | $ dart analyze |
測試。哦，這麼多測試。單元測試、整合測試，對於 Flutter，我們還有 Widget 測試。測試對於範例來說非常棒，因為測試傳達了如何使用程式碼片段的意圖。測試還與前面提到的 CI 管線結合使用，可以使程式碼庫保持常青。想要了解更多關於 Flutter 測試功能的資訊，可以到 如何測試 Flutter 應用程式 codelab 了解更多。Dart 和 Flutter 的 CI 命令分別為：
1 | $ flutter test # 適用於 Flutter 專案 |
如果你的程式碼儲存庫託管在 GitHub 上，那麼我建議你如果擁有 Dart 專案，請使用 Dart Setup 操作，如果擁有 Flutter 專案，請使用 Flutter Action。為了獲得額外積分，請考慮添加 Very Good Coverage 操作以保持高測試覆蓋率。既然你已經做到了這一步，你可能應該使用 工作流程狀態徽章 來宣傳你的 CI 狀態。
希望以上添加的項目清單能夠指導你，讓你的程式碼範例對你的目標受眾更有價值。
Writing a good code sample was originally published in Flutter on Medium, where people are continuing the conversation by highlighting and responding to this story.