コンテンツへスキップ

シャードの記述

Crystalシャードの作成とリリース方法。

シャードとは何か？

簡単に言うと、シャードはCrystalコードのパッケージであり、他のプロジェクトと共有および使用するために作られています。

詳細はShardsコマンドを参照してください。

はじめに

このチュートリアルでは、palindrome-exampleというCrystalライブラリを作成します。

ご存知ない方のために説明すると、回文とは、前からも後ろからも同じように綴られる単語のことです。例：racecar、mom、dad、kayak、madam

要件

Crystalシャードをリリースし、このチュートリアルに従うには、以下が必要です。

プロジェクトの作成

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プロパティは、簡潔で記述的である必要があります。

例：

name: palindrome-example

説明

shard.ymlにdescriptionを追加します。

descriptionは、シャードの検索と発見に使用される1行の説明です。

説明は次のとおりである必要があります。

  1. 情報提供
  2. 検出可能

最適化

見つけることができないと、誰もあなたのプロジェクトを使用することは困難です。シャードを発見するためのいくつかのサービスがあり、そのリストは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でホスティングしているかによって、ガイドが異なります。他の場所でホスティングしている場合は、ガイドを作成してこの本に追加してください！