⭐️

【Polaris和訳】Experiences/Command-line interfaces

2021/10/29に公開

Shopify

polaris

tech

この記事について

この記事は、Polaris/Experiences/Command-line interfacesの記事を和訳したものです。

記事内で使用する画像は、公式ドキュメント内の画像を引用して使用させていただいております。

Shopify アプリのご紹介

Shopify アプリである、「商品ページ発売予告アプリ | リテリア Coming Soon」は、商品ページを買えない状態のまま、発売日時の予告をすることができるアプリです。Shopify で Coming Soon 機能を実現することができます。

Shopify アプリである、「らくらく日本語フォント設定｜リテリア Font Picker」は、ノーコードで日本語フォントを使用できるアプリです。日本語フォントを導入することでブランドを演出することができます。

Command-line interfaces

コマンドラインツール（「コマンドラインインターフェイスツール」略して「CLI ツール」、または単に「CLI」とも呼ばれます）は、Shopify の開発者やサードパーティの開発者が毎日やり取りする生産性向上のためのツールです。

うまく作られた CLI は親しみやすく、開発者がタスクを効率的に実行するのに役立ちます。このような細部にこだわることが、CLI をしっかりしたものにするのです。

開発者が CLI を使用する場合、反復的な作業を行うことが多いため、CLI の最も重要な点はスピードです。この原則に焦点を合わせることで、認識する、あるいは実際のパフォーマンスが速くなるはずです。

これらのガイドラインの一部は、生産性と実行速度に重点を置いたチャットボットと Slack コマンドを構築するときにも使用できます。

Shopify アプリ CLI の動作。複数ステップのプロジェクト作成プロセスを示しています。

CLI の使用

ユーザーは、CLI の次のメカニズムに精通している必要があります。

タスクを実行するためのコマンドの入力
各コマンドやサブコマンドの詳細を教えてくれる、永続的なhelpコマンドがあります。
ctrl+Cで実行中のタスクを終了します
cdやmkdirなどのコマンドを使ったファイルシステムの移動と操作

CLI の構造

CLI には、トップレベルコマンド、コマンド（サブコマンドを伴う場合もある）、オプションの 3 つの要素が含まれていることがほとんどです。このパターンは「マルチコマンド CLI」と呼ばれています。

トップレベルコマンド
コマンド
1. コマンド名
2. コマンド引数
オプション（「フラグ」と呼ばれることもあります）
1. コマンド名
2. コマンド引数

例:

$ shopify create node --name=myApp
  ^       ^      ^      ^    ^
  1       2.1    2.2    3.1  3.2

詳細：CLI コマンドの構文。

これらは、引数を渡すのに有効で同じ方法です。

# 等号
$ shopify create node --name=myApp
# 等号無し
$ shopify create node --name myApp

適切に設計されたコマンドのコンポーネント

新しいコマンドまたはサブコマンドを作成するときは、注意すべき点がいくつかあります。

コマンドを実行する最も効率的な方法

ほとんどの場合、コマンドは自己完結型である必要があり、ユーザーからの追加の入力を必要としないはずです。たとえば、shopify populate productsコマンドを実行すると、コマンドがproduct nameやpriceなどを要求する可能性がある場合でも、ユーザーからの追加入力なしに実行されます。

新しいコマンドまたはサブコマンドを作成するときは、コマンドを自律的に実行するために絶対に必要な情報の量を考慮してください。コマンドに常に引数または追加情報が必要な場合は、スマートデフォルトを追加すると、コマンドの入力が速くなる可能性があります。

キーオーバーライドの引数を追加します

引数を使用すると、ユーザーはコマンドのデフォルトの実行をオーバーライドできます。例えば、ユーザーが shopify populate products を実行した場合、常識的なデフォルトでは 5 つの商品を作成します。しかし、ユーザーが 5 つ以上の製品を生成したい場合は、次のように引数を使用してデフォルトの動作をオーバーライドすることができます： shopify populate products --count=20.

新しいコマンドやサブコマンドを作成する際には、スマートデフォルトを設定し、ユーザーがそれを上書きできるようにするための最適な引数を公開する方法を検討します。

常に help を追加する

ヘルプは、ユーザーがコマンドの使用方法に関する詳細情報を見つけるための主要な方法です。これは CLI メンタルモデルに組み込まれているパターンであり、見落としてはなりません。

新しいコマンドやサブコマンドを追加するときは、必ずhelpページに記載されていることを確認してください。help コマンドを実行する標準的なパターンは、shopify help [command]で、help コマンドの命名規則のセクションで説明されています。

考慮すべきその他の表面部分

コマンドやサブコマンドが新しいファイルを作成したり、既存のファイルにコードラインを追加したりする場合は、その機能の使い方を説明するコメントやコンテンツを当該ファイルに追加することを検討してください。例えば、ユーザーが詳細を知ることができるドキュメント資料へのリンクを挿入したり、使用例を記載したりします。

可能であれば、ユーザーがその機能やファイルを仕事で最も効果的に使えるような状況を提供します。

命名規則

単語、小文字、ケバブケース

コマンド名とオプション名は、常にスペース、ハイフン、アンダースコア、またはその他の単語区切り文字を含まない単一の小文字の単語にする必要があります
複数の単語が混在することを避けるための明白な方法がない場合は、ケバブケースで分離します。

エイリアス

エイリアスは、よく使うコマンドとオプションの短縮版です。

例：

$ shopify serve
# エイリアス化されます
$ shopify s

エイリアス化されたオプションは、次の場合と同等です：

$ shopify serve --an-option
$ shopify serve --a
$ shopify serve -a

オプションのエイリアス（例：--branchを--bとする）は避けるべきですが、大幅な時間短縮ができる場合や、ユーザーが予想できる既存の慣習に従っている場合には有効です。

オプションのエイリアスは小文字または大文字にすることができます。大文字の場合は、小文字とは逆の意味を持つか(git log のように --paginate は -p、--no-paginate は -P とエイリアスされます)、または操作の「強制実行」を意味します（git checkout の -b や -B オプションのように）。

既存の慣習に従う

git、npm、railsなどの CLI は、新しいユーザーに親しみを感じてもらうために CLI が考慮しなければならない慣習を普及させました。

以下に、既存の慣習に従う必要のあるコマンド、オプション、およびエイリアスの例をいくつか示します。

バージョンナンバー

ユーザーは、対応するドキュメントをロードできるように、現在実行されている CLI のバージョンを知る必要があります。また、バグや問題を報告するときにバージョン番号を指定する必要があります。

$ shopify version
1.5.0
# （慣例により）エイリアスが必要です。
$ shopify --version
1.5.0

注:CLI がバージョンを返すために-vをサポートしている場合、必要に応じて-vが--verboseのエイリアスとしても機能することを確認してください。

ヘルプ

ユーザーは、役立つドキュメントを見ることができると考えて、これらのコマンドやオプションを使用します。

$ shopify help
# （慣例により）エイリアスが必要です。
$ shopify -h
$ shopify --h
$ shopify --help
# これらの構文は同等のものです。
$ shopify help <command>
$ shopify --help <command>
$ shopify -h <command>

コマンドにサブコマンドまたはオプションが必要な場合、CLI は、ユーザーがベアコマンドを実行するときに使用上のガイドラインを提供する場合があります。

$ my-cli config
Usage:
  my-cli config set <key> <value> [--global]
  my-cli config get [<key>]
  my-cli config list [--json]

ユーザーがタスクをより速く完了するのに役立つ場合に、よく使用される例を提供します。実行しても安全で、不可逆的または破壊的な動作を行わない例のみを表示してください。例をコピーアンドペーストしたユーザは、CLI にまだ慣れていない場合、その影響に気づかないことがあります。

冗長性のレベル

うまくいっているときの CLI は、ユーザーの邪魔にならないように、できるだけ簡潔に情報を出力する必要があります。しかし、開発者の中には、パフォーマンスの問題を診断したり、送受信のトラフィックを観察したりするために、バックグラウンドで実行されているプログラムの根本的な詳細を理解したいと考える人もいるでしょう。

--verbose（および任意で--very-verbose）オプションを使用すると、実行中のプロセスの詳細情報を知ることができます。

$ shopify serve --verbose
$ shopify serve -v
$ shopify serve --very-verbose
$ shopify serve -vv

構文

説明、ヘルプ、追加コンテンツ

CLI の説明は次のようになります。

ユーザーにとって最も重要な情報に焦点を当てる
簡潔で目を通しやすい：
- 一目で読めるシンプルでわかりやすい言葉を使う
- 説明の内容は、ほんの数語の短い文にしてください
- ピリオド、コンマ、セミコロンなどの句読点の使用は避けてください
- 感嘆符の使用は避けてください、適切なコピーは、感嘆符なしですでに十分なステートメントになっています
- 文章形式で書いてください

Polarisヘルプドキュメントのガイドラインに従ってください。

等号

オプションが値を持つ場合、コマンドラインのヘルプやドキュメントでは、オプションと引数の間に=記号を使用します（--option=<placeholder-value>）。これは、オプションとその値が単一のユニットとして成立していることを意味します。

次の表に、コマンドライン構文を示すために使用される表記法を示します（Microsoft のコマンドライン構文キーによる）。

表記法	説明
角括弧や中括弧なしのテキスト	見えたまま入力する必要がある項目。
`<山括弧内のテキスト>`	値を指定する必要があるプレースホルダー。
`[大括弧内のテキスト]`	オプショナルなアイテム。
`{中括弧内のテキスト}`	必須項目のセット。1 つを選択する必要があります。
垂直バー`	`
省略記号`…`	繰り返し使用できるアイテム。

CLI が既存のエコシステムまたはフレームワークと一緒に動作する場合は、ユーザーに馴染みのある規則に従ってください（たとえば、Rails CLI は大文字を使用してコマンドとオプションの引数を示します：rails generate GENERATOR、--environment=ENVIRONMENT）。

まれに、ドキュメントを読みやすくするために、構文を調整する必要がある場合もあります。このような場合には、最善の判断を下し、一貫性を保つようにしてください。

UX に関する高レベな考慮事項

CLI を作成する際の意思決定に役立つ高レベルな UX の考慮事項。

CLI との対話は会話体験です

CLI の使用は、最初は正しく行うのが難しい場合があります。コマンドの入力ミスによるものであれ、ローカル開発環境の破損によるものであれ、ユーザーは試行錯誤しながら CLI の使用方法を学びます。つまり、タスクを実行する最善の方法を見つけるために、何度も失敗を繰り返すことになります。

CLI を会話型の対話のように扱うことにより、このマルチステップエクスペリエンスに注意してください。ユーザーに失敗する権利を与え、その過程でユーザーを導きます。

冗長であっても、成功、待機、エラーといったあらゆる状態を伝えます

処理が成功した場合は出力を抑制し、エラーが発生した場合は出力を表示します

タスクがシステムの変更を必要とする場合にエラーを出し、インストールを完了する方法をユーザーに伝える

早期に失敗したプロセスがタスクの残りの部分に影響を与える場合は、できるだけ早くそのプロセスを終了させ、その理由をユーザーに伝えます。

1 行ごとに 1 つずつアイデアを出力します

タスクの自動実行に必要なすべての情報を求める

ユーザーがタスクを自動化できるように、プロンプトで CLI が要求する情報は、同等のコマンドまたはオプションでも入力できるようにしてください。

レイアウト

コンテンツを列に分けることで、コンテンツをより見やすくすることができます。例えば、選択肢とその説明は 2 つの列に分けられます。

$ cli help install
Usage: cli install [options]
Cli install is used to install all dependencies for a project.
Options:
  --no-default-rc      Prevent Cli from automatically detecting clirc files
  --enable-pnp         Enable the Plug'n'Play installation
  --disable-pnp        Disable the Plug'n'Play installation

資料

本ガイドラインは、これらのソースから得られたコンテンツを一部参考にしています。

Shopify UX ブログに掲載された、Shopify アプリ CLI を構築するために従ったコンテンツ戦略の原則
shopify CLI の概要と設計原則
コマンドラインインターフェイスのガイドライン
Google のコマンドラインドキュメントガイドライン
Heroku の CLI スタイルガイド
ナタリー・ジョンソンによる、楽しい CLI のためのアトラシアンの 10 の設計原則
ジェフ・ディッキーによる、Heroku の 12 ファクター CLI アプリ

Shopify によるパブリック CLI

Shopify App CLIは、Shopify のアプリをより早く構築するのに役立ちます。Node.js や Ruby on Rails のアプリの足場をすばやく作成し、多くの一般的な開発タスクを自動化します。
テーマキットは、Shopify のテーマを構築するために使用できます。
テーマチェックは、テーマ内のリキッドと JSON を分析することで、Shopify テーマとリキッドのベストプラクティスに従う手助けをします。
CLI UIは、素敵なコマンドラインユーザーインターフェースを生成するための小さなフレームワークです。

Shopify アプリのご紹介

Discussion

ログインするとコメントできます