跳至内容

编写碎片

如何编写和发布晶体碎片。

什么是碎片？

简而言之，碎片是晶体代码的包，用于与其他项目共享和使用。

有关详细信息，请参阅 碎片命令。

介绍

在本教程中，我们将创建一个名为palindrome-example的晶体库。

对于那些不知道的人来说，回文是一个正着读和反着读都一样的词。例如：racecar、mom、dad、kayak、madam

需求

为了发布晶体碎片并遵循本教程，您需要以下内容：

创建项目

首先使用 晶体编译器 的 init lib 命令创建一个具有标准目录结构的晶体库。

在您的终端中：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 docs 将您的代码和注释转换为互联的 API 文档。使用网络浏览器打开 /docs/ 目录中的文件，查看文档的编写情况。

请参阅以下有关在 GitHub/GitLab Pages 上托管编译器生成的文档的说明。

文档准备就绪且可用后，您可以在存储库中添加一个文档徽章，以便用户知道文档的存在。在 GitLab 中，此徽章属于项目，因此我们将在下面的 GitLab 说明中进行介绍，对于 GitHub，通常将其放置在自述文件的描述下方，如下所示：（请务必根据需要替换 <LINK-TO-YOUR-DOCUMENTATION>）

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

编写自述文件

一个好的自述文件可以成就或毁掉您的项目。 Awesome README 是一个很好的示例和资源集。

最重要的是，您的自述文件应说明：

  1. 您的库是什么
  2. 它能做什么
  3. 如何使用它

此说明应包含一些示例以及子标题。

注意

请务必将晶体生成的 README 模板中所有 [your-github-name] 实例替换为您的 GitHub/GitLab 用户名。如果您使用的是 GitLab，还需要将所有 github 实例更改为 gitlab。

编码风格

例如：

crystal tool format

要检查您的代码是否已正确格式化，或者检查使用格式化程序是否不会产生任何更改，只需在此命令末尾添加 --check。

例如：

crystal tool format --check

此检查适合作为 持续集成 中的一步添加。

编写 shard.yml 文件

规范 是您的规则手册。遵循它。

名称

您的 shard.yml 文件的 name 属性应简洁且描述性。

  • 搜索任何可用的 碎片数据库 以检查您的名称是否已被占用。

例如：

name: palindrome-example

描述

在您的 shard.yml 文件中添加一个 description。

description 是用于搜索和查找碎片的单行描述。

描述应：

  1. 信息量大
  2. 可发现性强

优化

如果无法找到您的项目，那么任何人都很难使用它。有多个服务可用于发现碎片，您可以从 晶体社区页面 上获取列表。

有些人正在寻找我们的库的确切功能，而另一些人则在寻找我们的库的一般功能。例如，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 上而有所不同。如果您在其他地方托管，请随时编写指南并将其添加到本书中！