跳至內容

撰寫 Shard

如何撰寫和發布 Crystal Shard。

什麼是 Shard？

簡而言之，Shard 是一個 Crystal 程式碼套件，旨在與其他專案共享和使用。

有關詳細資訊，請參閱Shards 命令。

簡介

在本教學中，我們將建立一個名為 palindrome-example 的 Crystal 函式庫。

對於那些不知道的人來說，迴文是一個單字，它的拼寫方式正反相同。例如：racecar、mom、dad、kayak、madam

需求

為了發布 Crystal Shard 並遵循本教學，您需要以下項目

建立專案

首先使用Crystal 編譯器的 init lib 命令來建立具有標準目錄結構的 Crystal 函式庫。

在您的終端機中：crystal init lib <YOUR-SHARD-NAME>

例如

$ crystal init lib palindrome-example
    create  palindrome-example/.gitignore
    create  palindrome-example/.editorconfig
    create  palindrome-example/LICENSE
    create  palindrome-example/README.md
    create  palindrome-example/shard.yml
    create  palindrome-example/src/palindrome-example.cr
    create  palindrome-example/spec/spec_helper.cr
    create  palindrome-example/spec/palindrome-example_spec.cr
Initialized empty Git repository in /<YOUR-DIRECTORY>/.../palindrome-example/.git/

...然後 cd 進入該目錄

例如

cd palindrome-example

然後 add 和 commit 以開始使用 Git 追蹤檔案

$ git add -A
$ git commit -am "First Commit"
[master (root-commit) 77bad84] First Commit
 8 files changed, 104 insertions(+)
 create mode 100644 .editorconfig
 create mode 100644 .gitignore
 create mode 100644 LICENSE
 create mode 100644 README.md
 create mode 100644 shard.yml
 create mode 100644 spec/palindrome-example_spec.cr
 create mode 100644 spec/spec_helper.cr
 create mode 100644 src/palindrome-example.cr

撰寫程式碼

您撰寫的程式碼由您決定，但您撰寫程式碼的方式會影響人們是否想使用您的函式庫和/或幫助您維護它。

測試程式碼

  • 測試您的程式碼。全部。這是任何人（包括您自己）知道它是否有效的唯一方法。
  • Crystal 有內建測試函式庫。使用它！

文件

  • 使用註解記錄您的程式碼。全部。甚至是私有方法。
  • Crystal 有內建文件產生器。使用它！

執行 crystal docs 以將您的程式碼和註解轉換為相互連結的 API 文件。在網頁瀏覽器中開啟 /docs/ 目錄中的檔案，以查看您的文件在整個過程中的外觀。

請參閱以下有關在 GitHub/GitLab Pages 上託管編譯器產生文件的說明。

一旦您的文件準備就緒且可用，您就可以將文件徽章新增至您的存放庫，讓使用者知道它的存在。在 GitLab 中，此徽章屬於專案，因此我們將在下面的 GitLab 說明中介紹它，對於 GitHub，通常將其放置在 README.md 中描述的下方，如下所示：（請務必相應地取代 <LINK-TO-YOUR-DOCUMENTATION>）

[![Docs](https://img.shields.io/badge/docs-available-brightgreen.svg)](<LINK-TO-YOUR-DOCUMENTATION>)

撰寫 README

一個好的 README 可以成就或毀掉您的專案。Awesome README 是一個關於該主題的範例和資源的精選集合。

最重要的是，您的 README 應說明

  1. 您的函式庫是什麼
  2. 它的功能是什麼
  3. 如何使用它

此說明應包含一些範例以及副標題。

注意

請務必將 Crystal 產生的 README 範本中的所有 [your-github-name] 實例替換為您的 GitHub/GitLab 使用者名稱。如果您使用的是 GitLab，您也會想要將所有 github 實例變更為 gitlab。

程式碼風格

例如

crystal tool format

要檢查您的程式碼是否格式正確，或檢查使用格式化工具是否不會產生任何變更，只需在此命令結尾新增 --check。

例如

crystal tool format --check

此檢查非常適合新增為持續整合中的一個步驟。

撰寫 shard.yml

規格是您的規則手冊。請遵循它。

名稱

您的 shard.yml 的 name 屬性應簡潔且具描述性。

  • 搜尋任何可用的shard 資料庫，以檢查您的名稱是否已被採用。

例如

name: palindrome-example

描述

將 description 新增至您的 shard.yml。

description 是一行描述，用於搜尋和尋找您的 shard。

描述應為

  1. 資訊豐富
  2. 易於發現

最佳化

如果他們找不到您的專案，任何人就很難使用它。有幾個服務可以探索 shards，Crystal 社群頁面上提供了列表。

有人正在尋找我們函式庫的確切功能和我們函式庫的一般功能。例如，Bob 需要一個迴文函式庫，但 Felipe 只是在尋找涉及文字的函式庫，而 Susan 正在尋找涉及拼寫的函式庫。

我們的 name 對於 Bob 搜尋「迴文」已經具有足夠的描述性。我們不需要重複迴文關鍵字。相反，我們將捕捉 Susan 對「拼寫」的搜尋和 Felipe 對「文字」的搜尋。

description: |
  A textual algorithm to tell if a word is spelled the same way forwards as it is backwards.

託管

從這裡開始，指南會根據您的儲存庫是託管在 GitHub 還是 GitLab 上而有所不同。如果您託管在其他地方，請隨時編寫一份指南並將其添加到本書中！