シャードの記述¶
Crystalシャードの作成とリリース方法。
シャードとは何か?¶
簡単に言うと、シャードはCrystalコードのパッケージであり、他のプロジェクトと共有および使用するために作られています。
詳細はShardsコマンドを参照してください。
はじめに¶
このチュートリアルでは、palindrome-exampleというCrystalライブラリを作成します。
ご存知ない方のために説明すると、回文とは、前からも後ろからも同じように綴られる単語のことです。例:racecar、mom、dad、kayak、madam
要件¶
Crystalシャードをリリースし、このチュートリアルに従うには、以下が必要です。
- Crystalコンパイラの動作するインストール
- Gitの動作するインストール
- GitHubまたはGitLabアカウント
プロジェクトの作成¶
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>
を適切に置き換えてください)
[](<LINK-TO-YOUR-DOCUMENTATION>)
READMEの記述¶
優れたREADMEは、プロジェクトの成否を左右します。Awesome READMEは、このトピックに関する例とリソースの良いキュレーションです。
最も重要なのは、READMEで次のことを説明することです。
- あなたのライブラリとは何か
- それが何をするのか
- 使用方法
この説明には、いくつかの例と小見出しを含める必要があります。
注記
Crystalによって生成されたREADMEテンプレート内の[your-github-name]
のすべてのインスタンスを、あなたのGitHub/GitLabユーザー名に置き換えてください。GitLabを使用している場合は、github
のすべてのインスタンスをgitlab
に変更する必要があります。
コーディングスタイル¶
- 独自のスタイルを持つことは問題ありませんが、Crystalチームによって定義されたいくつかのコア基準に準拠することで、コードの一貫性、可読性、他の開発者にとっての使いやすさを維持するのに役立ちます。
- Crystalの組み込みコードフォーマッターを使用して、ディレクトリ内のすべての
.cr
ファイルを自動的にフォーマットします。
例:
crystal tool format
コードが正しくフォーマットされているかどうか、またはフォーマッターを使用しても変更が発生しないかどうかを確認するには、このコマンドの最後に--check
を追加するだけです。
例:
crystal tool format --check
このチェックは、継続的インテグレーションのステップとして追加するのに適しています。
shard.yml
の記述¶
仕様はあなたのルールブックです。従ってください。
名前¶
shard.yml
のname
プロパティは、簡潔で記述的である必要があります。
- 利用可能なシャードデータベースを検索して、名前が既に使用されているかどうかを確認してください。
例:
name: palindrome-example
説明¶
shard.yml
にdescription
を追加します。
description
は、シャードの検索と発見に使用される1行の説明です。
説明は次のとおりである必要があります。
- 情報提供
- 検出可能
最適化¶
見つけることができないと、誰もあなたのプロジェクトを使用することは困難です。シャードを発見するためのいくつかのサービスがあり、そのリストは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でホスティングしているかによって、ガイドが異なります。他の場所でホスティングしている場合は、ガイドを作成してこの本に追加してください!