HN 日本語サマリー

← 一覧へ戻る
プログラミング

コマンドラインインターフェースガイドライン

Command Line Interface Guidelines (clig.dev)

136 pointsby subset31 コメント

要約

この記事は、現代のUNIX原則をアップデートし、より優れたコマンドラインプログラムを作成するためのオープンソースガイドです。コマンドラインの歴史的背景、現代におけるその重要性、そして人間中心のデザイン、単純な部品の組み合わせ、プログラム間の一貫性といった、良いCLI設計のための哲学と具体的なガイドラインを提供しています。

全文翻訳

コマンドラインインターフェースガイドライン

現代のコマンドラインプログラムをより良くするためのオープンソースガイドです。伝統的なUNIXの原則を取り入れ、現代に合わせて更新しています。

Aanand Prasad
Squarespaceのエンジニア、Docker Composeの共同作成者。
@aanandprasad

Ben Firshman
Replicateの共同創業者、Docker Composeの共同作成者。
@bfirsh

Carl Tashian
Smallstepのオフロードエンジニア、Zipcarの初期エンジニア、Troveの共同創業者。
tashian.com @tashian

Eva Parish
Squarespaceのテクニカルライター、O’Reillyの寄稿者。
evaparish.com @evpari

デザイン: Mark Hurrell。初期貢献者であるAndreas Jansson、ドラフトレビュー担当のAndrew Reitz、Ashley Williams、Brendan Falk、Chester Ramey、Dj Walker-Morgan、Jacob Maine、James Coglan、Michael Dwan、Steve Klabnikに感謝します。

ガイドやCLIデザインについて議論したい場合は、Discordにご参加ください。

前書き

1980年代、パーソナルコンピュータに何かをさせるには、C:\>や~\$に直面したときに何を入力すべきかを知る必要がありました。ヘルプは厚いスパイラル綴じのマニュアルの形で提供されていました。エラーメッセージは不透明でした。あなたを救ってくれるStack Overflowはありませんでした。しかし、幸運にもインターネットにアクセスできれば、Usenetからヘルプを得ることができました。これは、あなたと同じように不満を抱えている他の人々でいっぱいの初期のインターネットコミュニティでした。彼らはあなたの問題を解決するのを助けてくれるか、少なくとも道徳的なサポートと仲間意識を提供してくれました。

40年後、コンピュータは誰にとってもはるかにアクセスしやすくなりましたが、それはしばしば低レベルのエンドユーザーコントロールを犠牲にした結果です。多くのデバイスでは、壁に囲まれた庭やアプリストアといった企業の利益に反するため、コマンドラインへのアクセスが全くありません。

今日のほとんどの人は、コマンドラインが何であるかを知りませんし、ましてやなぜそれにこだわる必要があるのかも理解していません。コンピューティングのパイオニアであるAlan Kayが2017年のインタビューで述べたように、「人々はコンピューティングが何であるかを理解していないため、iPhoneにそれがあると思っています。そしてその幻想は、『ギターヒーロー』が本物のギターと同じであるという幻想と同じくらい悪いのです。」

Kayの言う「本物のギター」はCLIではありません――正確には。彼は、CLIのパワーを提供し、テキストファイルでのソフトウェア作成を超越する方法について話していました。Kayの弟子たちの間には、数十年間私たちが住んできたテキストベースの局所的最適解から抜け出す必要があるという信念があります。

コンピュータを全く異なる方法でプログラムする未来を想像するのはエキサイティングです。今日でさえ、スプレッドシートは断然最も人気のあるプログラミング言語であり、ノーコード運動は、才能あるプログラマーへの激しい需要を置き換えることを試みながら、急速に勢いを増しています。

しかし、その古くさく、数十年前の制約と不可解な癖にもかかわらず、コマンドラインは依然としてコンピュータの中で最も汎用性の高い領域です。それは、カーテンの裏側を覗き、何が本当に起こっているのかを見て、GUIでは提供できないレベルの洗練さと深さでマシンと創造的に対話することを可能にします。それは、それを学びたい人なら誰でも、ほぼすべてのラップトップで利用できます。インタラクティブに使用することも、自動化することもできます。そして、それはシステムの他の部分ほど速く変化しません。その安定性には創造的な価値があります。

したがって、まだそれがあるうちに、その有用性とアクセシビリティを最大化するように努めるべきです。

初期の頃から、コンピュータのプログラムの作り方は大きく変わりました。過去のコマンドラインはマシンファーストでした:スクリプトプラットフォームの上に置かれたREPLに過ぎませんでした。しかし、汎用インタプリタ言語が繁栄するにつれて、シェルスクリプトの役割は縮小しました。今日のコマンドラインはヒューマンファーストです:あらゆる種類のツール、システム、プラットフォームへのアクセスを提供するテキストベースのUIです。過去には、エディタはターミナルの中にありましたが、今日では、ターミナルはエディタの機能であることが同様に多いです。そして、gitのようなマルチツールコマンドが数多く登場しています。コマンドの中にコマンドがあり、アトミックな関数ではなく、完全なワークフローを実行する高レベルコマンドがあります。

伝統的なUNIX哲学に触発され、より楽しくアクセスしやすいCLI環境を奨励することへの関心から、そしてプログラマーとしての私たちの経験に導かれて、コマンドラインプログラムを構築するためのベストプラクティスとデザイン原則を再検討する時期が来たと判断しました。

コマンドラインよ永遠なれ!

はじめに

このドキュメントは、高レベルのデザイン哲学と具体的なガイドラインの両方をカバーしています。実践者としての私たちの哲学は、あまり哲学的に考えすぎないことなので、ガイドラインに重点を置いています。私たちは例から学ぶことを信じているので、たくさんの例を提供しました。

emacsやvimのようなフルスクリーンターミナルプログラムは、このガイドでは扱いません。フルスクリーンプログラムはニッチなプロジェクトであり、私たちのごく一部しかそれを設計する立場にはならないでしょう。

また、このガイドはプログラミング言語やツール全般については中立です。

このガイドは誰のためか?

  • CLIプログラムを作成していて、そのUIデザインのための原則と具体的なベストプラクティスを探しているなら、このガイドはあなたのためです。
  • プロフェッショナルな「CLI UIデザイナー」なら、それは素晴らしいです――私たちはあなたから学びたいです。
  • 40年間のCLIデザインの慣習に反するような、明白なミスを避けたいなら、このガイドはあなたのためです。
  • プログラムの良いデザインと役立つヘルプで人々を喜ばせたいなら、このガイドは間違いなくあなたのためです。
  • GUIプログラムを作成しているなら、このガイドはあなたのためではありません――それでも読むことにしたら、GUIのアンチパターンについていくつか学べるかもしれません。
  • Minecraftの没入型フルスクリーンCLIポートを設計しているなら、このガイドはあなたのためではありません。(でも、それを見るのが待ちきれません!)

哲学

これらは、私たちが考える優れたCLIデザインの基本原則です。

人間中心のデザイン

伝統的に、UNIXコマンドは他のプログラムによって主に使用されることを前提に書かれていました。それらは、グラフィカルアプリケーションよりもプログラミング言語の関数により多くの共通点がありました。

今日、多くのCLIプログラムは主に(あるいは排他的に)人間によって使用されていますが、そのインタラクションデザインの多くは過去の遺産を引きずっています。この遺産の一部を捨てる時が来ました。コマンドが主に人間によって使用されるのであれば、それはまず人間向けに設計されるべきです。

連携して機能するシンプルな部品

オリジナルのUNIX哲学の核心的な教義は、クリーンなインターフェースを持つ小さくシンプルなプログラムを組み合わせてより大きなシステムを構築できるという考え方です。それらのプログラムにますます多くの機能を追加するのではなく、必要に応じて再構成できるモジュール式のプログラムを作成します。

昔は、パイプとシェルスクリプトがプログラムを組み合わせてプロセスを構築する上で重要な役割を果たしました。汎用インタプリタ言語の台頭によりその役割は低下したかもしれませんが、決して消滅したわけではありません。さらに、CI/CD、オーケストレーション、設定管理といった形での大規模な自動化が盛んになりました。プログラムを構成可能にすることは、これまで以上に重要です。

幸いなことに、この目的のために設計されたUNIX環境の長年の慣習は、今日でも私たちを助けてくれます。標準のin/out/err、シグナル、終了コード、その他のメカニズムは、異なるプログラムがうまく連携することを保証します。プレーンな行ベースのテキストは、コマンド間で簡単にパイプできます。JSONは、はるかに新しい発明ですが、必要なときに構造を提供し、コマンドラインツールをWebとより簡単に統合できるようにします。

あなたが構築しているソフトウェアが何であれ、人々があなたが予期しない方法で使用することを絶対に確信できます。あなたのソフトウェアは、より大きなシステムの一部になるでしょう――あなたの唯一の選択肢は、それがまともな一部であるかどうかです。

最も重要なのは、構成可能性のために設計することが、人間中心のデザインと対立する必要はないということです。このドキュメントの多くのアドバイスは、両方をどのように達成するかについてのものです。

プログラム間の整合性

ターミナルの慣習は私たちの指にハードワイヤードされています。コマンドラインの構文、フラグ、環境変数などを学ぶために初期費用を支払いましたが、それは長期的な効率に報います...プログラムが整合していればの話です。

可能な限り、CLIは既存のパターンに従うべきです。それがCLIを直感的で推測可能にし、ユーザーを効率的にする理由です。

とはいえ、整合性が使いやすさと衝突することもあります。例えば、多くの長年のUNIXコマンドはデフォルトで多くの情報を出力しないため、コマンドラインにあまり慣れていない人々を混乱させたり不安にさせたりすることがあります。

慣習に従うことがプログラムの使いやすさを損なう場合は、それに従わない時かもしれません――しかし、そのような決定は慎重に行われるべきです。

(ちょうど)十分なことを言う

ターミナルは純粋な情報の世界です。情報をインターフェースと見なすことができます――そして、他のインターフェースと同様に、多すぎたり少なすぎたりすることがよくあります。

コマンドが数分間ハングしてユーザーが壊れているのではないかと疑い始めるとき、それは少なすぎると言えます。コマンドがデバッグ出力のページをダンプして、本当に重要なものを緩い破片の海に溺れさせるとき、それは多すぎると言えます。最終的な結果は同じです:明確さの欠如、ユーザーを混乱させ、イライラさせます。

このバランスを正しく取るのは非常に難しいですが、ソフトウェアがユーザーを力づけ、奉仕するためには絶対に不可欠です。

発見の容易さ

機能を発見可能にするという点では、GUIは優位に立っています。実行できるすべてが画面上に表示されるため、何も学ぶ必要なく必要なものを見つけることができ、可能性すら発見できるかもしれません。

コマンドラインインターフェースはこれとは逆であると想定されています――すべてを覚える必要があるということです。オリジナルのMacintosh Human Interface Guidelines(1987年発行)は、「(覚える&タイプするのではなく)見て&指す」ことを推奨しています。あたかもどちらか一方しか選べないかのように。

これらのことは相互排他的である必要はありません。コマンドラインを使用する効率性はコマンドを覚えることから来ますが、コマンドが学習と記憶を助けることができない理由はありません。発見可能なCLIは、包括的なヘルプテキストを持ち、たくさんの例を提供し、次に実行すべきコマンドを提案し、エラーが発生した場合に何をすべきかを提案します。GUIから盗めるアイデアがたくさんあり、CLIを学習しやすく、パワーユーザーにとっても使いやすくすることができます。

引用: The Design of Everyday Things (Don Norman), Macintosh Human Interface Guidelines

会話が標準

GUIデザイン、特に初期の頃は、メタファー(デスクトップ、ファイル、フォルダ、リサイクルビン)を多用しました。コンピュータがまだ正当性を確立しようとしていたため、それは理にかなっていました。メタファーの実装の容易さは、GUIがCLIに対して持っていた大きな利点の1つでした。皮肉なことに、CLIは常に偶然のメタファーを体現してきました:それは会話です。

最も単純なコマンドを除いて、プログラムの実行は通常、複数の呼び出しを伴います。通常、これは、一度で正しく行うのが難しいためです:ユーザーはコマンドを入力し、エラーを受け取り、コマンドを変更し、別のエラーを受け取り、そしてそれが機能するまで続きます。この繰り返し失敗による学習モードは、ユーザーがプログラムと行っている会話のようなものです。

しかし、試行錯誤だけが会話型のインタラクションではありません。他にもあります:

  • ツールを設定するためのコマンドを実行し、実際に使用を開始するために実行すべきコマンドを学ぶ。
  • 操作を実行するために複数のコマンドを実行し、最後にそれを実行するためのコマンドを実行する(例:複数のgit addの後、git commit)。
  • システムを探索する――例えば、多くのcdとlsを実行してディレクトリ構造の感覚をつかむ、またはgit logとgit showを実行してファイルの履歴を探索する。
  • 複雑な操作を実行する前に、そのドライランを行う。

コマンドラインインタラクションの会話的な性質を認識することは、そのデザインに適切なテクニックを適用できることを意味します。ユーザー入力が無効な場合に可能な修正を提案したり、ユーザーが多段階プロセスを経ている場合に中間状態を明確にしたり、恐ろしいことをする前にすべてが順調であることを確認したりできます。

意図したかどうかに関わらず、ユーザーはあなたのソフトウェアと会話しています。最悪の場合、それは彼らを愚かで resentful にさせる敵対的な会話です。最良の場合、それは彼らを迅速に進ませ、新たな知識と達成感を与える楽しい交換です。

さらに読む: The Anti-Mac User Interface (Don Gentner and Jakob Nielsen)

堅牢性

堅牢性は、客観的かつ主観的な特性です。ソフトウェアは、もちろん堅牢でなければなりません:予期しない入力は優雅に処理されるべきであり、操作は可能な限り冪等であるべきです。しかし、それはまた、堅牢であるように感じられるべきです。

あなたのソフトウェアが壊れないように感じられるようにしたいのです。それは、大きな機械的な機械のように、壊れやすいプラスチックの「ソフトスイッチ」ではなく、即応性があるように感じられるようにしたいのです。

主観的な堅牢性には、細部への注意と、何が起こりうるかについての深い考察が必要です。それは多くの小さなことです:ユーザーに何が起こっているかを知らせる、一般的なエラーの意味を説明する、恐ろしく見えるスタックトレースを出力しないこと。一般的に、堅牢性はシンプルさを保つことからも来ます。多くの特別なケースと複雑なコードは、プログラムを壊れやすくする傾向があります。

共感

コマンドラインツールはプログラマーの創造的なツールキットなので、使用していて楽しいものであるべきです。これは、それらをビデオゲームに変えたり、多くの絵文字を使ったりすることを意味するのではありません(絵文字自体に本質的な問題はありませんが 😉)。それは、ユーザーにあなたが彼らの味方であること、彼らの成功を願っていること、彼らの問題とその解決策について慎重に考えたことを感じさせることを意味します。

彼らがそのように感じることを保証するアクションのリストはありませんが、私たちの助言に従うことで、ある程度そこに到達できることを願っています。ユーザーを喜ばせるということは、あらゆる場面で期待を超えることを意味し、それは共感から始まります。

カオス

ターミナルの世界は混乱しています。矛盾があちこちにあり、私たちを遅らせ、自己疑念に陥らせます。

しかし、このカオスが力の源であったことは否定できません。ターミナルは、一般的にUNIXから派生したコンピューティング環境と同様に、構築できるものにほとんど制約を課しません。その空間では、あらゆる種類の発明が開花しました。

このドキュメントが、数十年にわたるコマンドラインの伝統に反するアドバイスと並んで、既存のパターンに従うように懇願しているのは皮肉です。私たちも、他の誰よりもルールを破っています。

あなたもルールを破らなければならない時が来るかもしれません。意図と明確な目的を持ってそうしてください。

「生産性またはユーザー満足度に明らかに有害な場合は、標準を放棄せよ。」 — Jef Raskin, The Humane Interface

ガイドライン

これは、コマンドラインプログラムをより良くするためにできることの具体的なリストです。

最初のセクションには、従う必要がある必須事項が含まれています。これらを間違えると、プログラムは使いにくいか、または悪いCLI市民になります。

残りは「あれば嬉しい」ものです。時間とエネルギーがあれば、これらを追加すると、プログラムは平均的なプログラムよりもはるかに良くなります。

考え方は、プログラムのデザインについてあまり深く考えたくない場合は、考える必要はありません。これらのルールに従えば、プログラムはおそらく良いものになるでしょう。一方で、ルールがあなたのプログラムに間違っていると判断した場合は、それでも構いません。(恣意的なルールに従わないからといって、あなたのプログラムを拒否する中央当局はありません。)

また、これらのルールは石に刻まれたものではありません。もしあなたが良い理由で一般的なルールに同意しない場合は、変更を提案していただけると幸いです。

基本

従う必要がある基本的なルールがいくつかあります。これらを間違えると、プログラムは非常に使いにくいか、完全に壊れてしまいます。

可能な場合は、コマンドライン引数解析ライブラリを使用してください。 言語の組み込みのものか、優れたサードパーティのものか、どちらかを使用してください。通常、それらは引数、フラグ解析、ヘルプテキスト、さらにはスペルミス提案などを sensible に処理します。

以下は私たちが気に入っているものです:

成功時にはゼロ、失敗時には非ゼロの終了コードを返してください。 終了コードはスクリプトがプログラムが成功したか失敗したかを判断する方法なので、これを正しく報告する必要があります。非ゼロの終了コードを最も重要な失敗モードにマッピングしてください。

出力をstdoutに送信してください。 コマンドの主な出力はstdoutに送られるべきです。機械可読なものもすべてstdoutに送られるべきです――これがデフォルトでパイプが送信する場所です。

メッセージをstderrに送信してください。 ログメッセージ、エラーなどはすべてstderrに送られるべきです。これは、コマンドがパイプで接続されている場合、これらのメッセージがユーザーに表示され、次のコマンドに渡されないことを意味します。

ヘルプ

要求されたときに詳細なヘルプテキストを表示してください。 -hまたは--helpフラグが渡されたときにヘルプを表示してください。これはサブコマンドにも適用され、それらも独自のヘルプテキストを持つ場合があります。

デフォルトで簡潔なヘルプテキストを表示してください。 myappまたはmyapp subcommandが機能するために引数を必要とし、引数なしで実行された場合、簡潔なヘルプテキストを表示してください。

プログラムがデフォルトでインタラクティブな場合(例:npm init)、このガイドラインを無視できます。

簡潔なヘルプテキストには以下のみを含めるべきです:

  • プログラムが何をするかの説明。
  • 1つか2つの例示的な呼び出し。
  • フラグの説明(多数ある場合は除く)。
  • 詳細情報については--helpフラグを渡すように促す指示。

jqはこれをうまく行っています。jqと入力すると、紹介文と例が表示され、次に完全なフラグリストについてはjq --helpを渡すように促されます。

$ jq
jq - commandline JSON processor [version 1.6]

Usage:    jq [options] <jq filter> [file...]
    jq [options] --args <jq filter> [strings...]
    jq [options] --jsonargs <jq filter> [JSON_TEXTS...]

jq is a tool for processing JSON inputs, applying the given filter to
its JSON text inputs and producing the filter's results as JSON on
standard output.

The simplest filter is ., which copies jq's input to its output
unmodified (except for formatting, but note that IEEE754 is used
for number representation internally, with all that that implies).

For more advanced filters see the jq(1) manpage ("man jq")
and/or https://stedolan.github.io/jq

Example:

    $ echo '{"foo": 0}' | jq .
    {
        "foo": 0
    }

For a listing of options, use jq --help.

-hおよび--helpが渡されたときに完全なヘルプを表示してください。 これらすべてがヘルプを表示するはずです:

$ myapp
$ myapp --help
$ myapp -h

渡された他のフラグや引数は無視してください――どんなものにも-hを追加でき、ヘルプが表示されるはずです。-hを過負荷にしないでください。

プログラムがgitのようなものである場合、以下もヘルプを提供するはずです:

$ myapp help
$ myapp help subcommand
$ myapp subcommand --help
$ myapp subcommand -h

フィードバックと問題のためのサポートパスを提供してください。 ウェブサイトまたはGitHubリンクをトップレベルのヘルプテキストに含めるのが一般的です。

ヘルプテキストでは、ドキュメントのWebバージョンにリンクしてください。 サブコマンドに特定のページやアンカーがある場合は、直接リンクしてください。これは、Web上に詳細なドキュメントがある場合、または何か行動を説明するのに役立つ追加の読み物がある場合に特に役立ちます。

例から始めてください。 ユーザーは他の形式のドキュメントよりも例を使用する傾向があるため、ヘルプページ、特に一般的で複雑な使用例を最初に示してください。それが何をしているかを説明するのに役立ち、長すぎない場合は、実際の出力も示してください。

一連の例でストーリーを語り、複雑な使用例へと進むことができます。

例がたくさんある場合は、別の場所に置いてください。 チートシートコマンドやWebページに。網羅的で高度な例を持つことは有用ですが、ヘルプテキストを非常に長くしたくはありません。

ヘルプテキストの先頭に最も一般的なフラグとコマンドを表示してください。 たくさんのフラグがあっても構いませんが、非常に一般的なものがある場合は、最初に表示してください。例えば、Gitコマンドは、開始方法と最も一般的に使用されるサブコマンドを最初に表示します:

$ git
usage: git [--version] [--help] [-C <path>] [-c <name>=<value>]
           [--exec-path[=<path>]] [--html-path] [--man-path] [--info-path]
           [-p | --paginate | -P | --no-pager] [--no-replace-objects] [--bare]
           [--git-dir=<path>] [--work-tree=<path>] [--namespace=<name>]
           <command> [<args>]

These are common Git commands used in various situations:

start a working area (see also: git help tutorial)
   clone      Clone a repository into a new directory
   init       Create an empty Git repository or reinitialize an existing one

work on the current change (see also: git help everyday)
   add        Add file contents to the index
   mv         Move or rename a file, a directory, or a symlink
   reset      Reset current HEAD to the specified state
   rm         Remove files from the working tree and from the index

examine the history and state (see also: git help revisions)
   bisect     Use binary search to find the commit that introduced a bug
   grep       Print lines matching a pattern
   log        Show commit logs
   show       Show various types of objects
   status     Show the working tree status
…

ヘルプテキストにフォーマットを使用してください。 太字の見出しはスキャンをはるかに容易にします。ただし、ターミナルに依存しない方法で実行するようにしてください。ユーザーがエスケープ文字の壁を見つめることにならないようにします。


$ heroku apps --help
list your apps

USAGE
  $ heroku apps

OPTIONS
  -A, --all          include apps in all teams
  -p, --personal     list apps in personal account when a default team is set
  -s, --space=space  filter by space
  -t, --team=team    team to use
  --json             output in json format

EXAMPLES
  $ heroku apps
  === My Apps
  example
  example2

  === Collaborated Apps
  theirapp   other@owner.name

COMMANDS
  apps:create     creates a new app
  apps:destroy    permanently destroy an app
  apps:errors     view app errors
  apps:favorites  list favorited apps
  apps:info       show detailed app information
  apps:join       add yourself to a team app
  apps:leave      remove yourself from a team app
  apps:lock       prevent team members from joining an app
  apps:open       open the app in a web browser
  apps:rename     rename an app
  apps:stacks     show the list of available stacks
  apps:transfer   transfer applications to another user or team
  apps:unlock     unlock an app so any team member can join

注:heroku apps --helpがページャーを介してパイプされると、コマンドはエスケープ文字を一切出力しません。

ユーザーが何か間違ったことをして、あなたが何を意図していたかを推測できるなら、それを提案してください。 例えば、brew update jqは、brew upgrade jqを実行すべきだと教えてくれます。

提案されたコマンドを実行するかどうか尋ねることができますが、強制しないでください。例えば:

$ heroku pss
 ›   Warning: pss is not a heroku command.
Did you mean ps? [y/n]: 

修正された構文を提案する代わりに、それを実行してしまいたい誘惑に駆られるかもしれません。時にはそれが正しいことですが、常にそうとは限りません。

第一に、無効な入力は単純なタイプミスを必ずしも意味しません――それはしばしばユーザーが論理的な間違いを犯したか、シェル変数を誤用したことを意味する可能性があります。彼らが何を意図したかを推測することは危険です、特にその結果のアクションが状態を変更する場合。

第二に、ユーザーが入力したものを変更した場合、彼らは正しい構文を学ばないことに注意してください。実質的に、あなたは彼らが入力した方法が有効で正しいと判断し、それを無期限にサポートすることを約束します。その決定を意図的に行い、両方の構文を文書化してください。

さらに読む: “Do What I Mean”

コマンドが何かにパイプされることを期待していて、stdinがインタラクティブなターミナルである場合、すぐにヘルプを表示して終了してください。 これは、catのようにハングするのではなく、ハングしないことを意味します。あるいは、stderrにログメッセージを出力することもできます。

ドキュメント

ヘルプテキストの目的は、ツールが何であるか、利用可能なオプションは何か、そして最も一般的なタスクを実行する方法についての簡単な、即時の感覚を提供することです。一方、ドキュメントは、詳細に入る場所です。それは、人々があなたのツールが何のためであるか、何のためではないか、どのように動作するか、そして彼らが必要とするかもしれないすべてを行う方法を理解するために行く場所です。

Webベースのドキュメントを提供してください。 人々はオンラインであなたのツールのドキュメントを検索し、他の人に特定の箇所にリンクできるようにする必要があります。Webは最も包括的なドキュメント形式です。

ターミナルベースのドキュメントを提供してください。 ターミナルでのドキュメントにはいくつかの利点があります:アクセスが速く、ツールの特定のインストールバージョンと同期したままになり、インターネット接続なしで動作します。

manページを提供することを検討してください。 manページ、Unixのオリジナルのドキュメントシステムは、今日でも使用されており、多くのユーザーはあなたのツールについて学ぶ最初のステップとして、反射的にman mycmdをチェックするでしょう。それらを生成しやすくするために、ronnのようなツールを使用できます(これはWebドキュメントも生成できます)。

しかし、誰もがmanを知っているわけではなく、すべてのプラットフォームで動作するわけではないので、ターミナルドキュメントもツール自体からアクセスできるようにする必要があります。例えば、gitとnpmはhelpサブコマンドを介してmanページにアクセスできるようにしているので、npm help lsはman npm-lsと同等です。

NPM-LS(1)                                                            NPM-LS(1)

NAME
       npm-ls - List installed packages

SYNOPSIS
         npm ls [[<@scope>/]<pkg> ...]

         aliases: list, la, ll

DESCRIPTION
       This command will print to stdout all the versions of packages that are
       installed, as well as their dependencies, in a tree-structure.

       ...
出力

人間が読める出力が最優先です。 人間が第一、機械が第二です。特定の出力ストリーム(stdoutまたはstderr)が人間によって読み取られているかどうかを判断するための最もシンプルで直接的なヒューリスティックは、それがTTYであるかどうかです。あなたが使用している言語に関わらず、これを行うためのユーティリティまたはライブラリがあるでしょう(例:Python, Node, Go)。

TTYとは何かについてのさらなる読み物:What is a TTY?

人間が読める出力が機械が読める出力を妨げる場合、--plainを使用して、grepやawkのようなツールと統合するためにプレーンな表形式のテキスト形式で出力を表示してください。 場合によっては、人間が読めるように情報を異なる方法で出力する必要があるかもしれません。

例えば、行ベースのテーブルを表示している場合、セルを複数の行に分割して、画面幅内に収めながらより多くの情報を含めることを選択するかもしれません。これは、1行あたり1つのデータという期待される動作を壊すため、スクリプト用に--plainフラグを提供する必要があります。これはすべての操作を無効にし、1レコードあたり1行を出力します。

--jsonが渡された場合は、フォーマットされたJSONとして出力を表示してください。 JSONはプレーンテキストよりも構造化されているため、複雑なデータ構造の出力と処理をはるかに容易にします。jqは、コマンドラインでJSONを扱う一般的なツールであり、JSONツールのエコシステム全体が存在し、JSONを出力および操作します。

Webでも広く使用されているため、プログラムの入力と出力としてJSONを使用することで、curlを使用してWebサービスと直接パイプできます。

成功時に出力を表示しますが、簡潔に保ってください。 伝統的に、何も問題がない場合、UNIXコマンドはユーザーに何も出力しません。これはスクリプトで使用される場合には理にかなっていますが、人間が使用する場合にはコマンドがハングしたり壊れたように見えたりすることがあります。例えば、cpは時間がかかっても何も表示しません。

何も出力しないことが最良のデフォルト動作であることはまれですが、通常は少ない方に傾くのが最良です。

何も出力したくない場合(例えば、シェルスクリプトで使用する場合)は、stderrを/dev/nullにリダイレクトする面倒を避けるために、-qオプションを提供して、必須でないすべての出力を抑制できます。

状態を変更した場合は、ユーザーに伝えてください。 コマンドがシステムの状態を変更した場合、何が起こったのかを説明することは特に価値があります。これにより、ユーザーはシステムの状態を頭の中でモデル化できます――特に結果がユーザーが要求したことと直接一致しない場合。

例えば、git pushは、何をしているのか、リモートブランチの新しい状態がどうなっているのかを正確に伝えます:

$ git push
Enumerating objects: 18, done.
Counting objects: 100% (18/18), done.
Delta compression using up to 8 threads
Compressing objects: 100% (10/10), done.
Writing objects: 100% (10/10), 2.09 KiB | 2.09 MiB/s, done.
Total 10 (delta 8), reused 0 (delta 0), pack-reused 0
remote: Resolving deltas: 100% (8/8), completed with 8 local objects.
To github.com:replicate/replicate.git
 + 6c22c90...a2a5217 bfirsh/fix-delete -> bfirsh/fix-delete

システムの現在の状態を簡単に確認できるようにしてください。 プログラムが多くの複雑な状態変更を行い、それがファイルシステムで直接見えない場合、それを簡単に表示できるようにしてください。

例えば、git statusは、Gitリポジトリの現在の状態に関する可能な限り多くの情報と、状態を変更する方法のヒントを提供します:

$ git status
On branch bfirsh/fix-delete
Your branch is up to date with 'origin/bfirsh/fix-delete'.

Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
	modified:   cli/pkg/cli/rm.go

no changes added to commit (use "git add" and/or "git commit -a")

ユーザーが実行すべきコマンドを提案してください。 複数のコマンドがワークフローを形成する場合、次に実行できるコマンドをユーザーに提案することは、プログラムの使用方法を学習し、新しい機能を発見するのに役立ちます。例えば、上記のgit status出力では、表示している状態を変更するために実行できるコマンドを提案しています。

プログラムの内部世界の境界を越えるアクションは、通常、明示的であるべきです。 これには以下が含まれます:

  • ユーザーが明示的に引数として渡さなかったファイル(それらのファイルがキャッシュのようなプログラムの内部状態を保存している場合を除く)の読み書き。
  • リモートサーバーとの通信、例:ファイルのダウンロード。

情報密度を上げろ――ASCIIアートで! 例えば、lsは権限をスキャン可能な方法で表示します。最初に見たときは、ほとんどの情報を無視できます。次に、それがどのように機能するかを学ぶにつれて、より多くのパターンを時間とともに拾い上げます。

-rw-r--r-- 1 root root     68 Aug 22 23:20 resolv.conf
lrwxrwxrwx 1 root root     13 Mar 14 20:24 rmt -> /usr/sbin/rmt
drwxr-xr-x 4 root root   4.0K Jul 20 14:51 security
drwxr-xr-x 2 root root   4.0K Jul 20 14:53 selinux
-rw-r----- 1 root shadow  501 Jul 20 14:44 shadow
-rw-r--r-- 1 root root    116 Jul 20 14:43 shells
drwxr-xr-x 2 root root   4.0K Jul 20 14:57 skel
-rw-r--r-- 1 root root      0 Jul 20 14:43 subgid
-rw-r--r-- 1 root root      0 Jul 20 14:43 subuid

意図を持って色を使用してください。 例えば、ユーザーに気づいてほしいテキストをハイライトしたり、エラーを示すために赤を使用したりしたい場合があります。使いすぎないでください――すべてが異なる色の場合、色は何も意味せず、読み取りを困難にするだけです。

プログラムがターミナルにない場合、またはユーザーが要求した場合に色を無効にしてください。 これらのことは色を無効にするべきです:

  • stdoutまたはstderrがインタラクティブなターミナル(TTY)ではない。個別にチェックするのが最善です――stdoutを別のプログラムにパイプしている場合、stderrで色を取得することは依然として有用です。
  • NO_COLOR環境変数が設定されており、空でない場合(値に関わらず)。
  • TERM環境変数がdumbという値を持っている場合。
  • ユーザーが--no-colorオプションを渡した場合。
  • 特定のプログラムの色を無効にしたい場合のために、MYAPP_NO_COLOR環境変数も追加したい場合があります。

さらに読む: no-color.org, 12 Factor CLI Apps

stdoutがインタラクティブなターミナルでない場合、アニメーションを表示しないでください。 これは、CIログ出力でプログレスバーがクリスマスツリーになるのを防ぎます。

シンボルや絵文字を、それが明確にする場合に役立ててください。 複数のものを区別したり、ユーザーの注意を引いたり、単にキャラクターを加えたりする必要がある場合、絵は言葉よりも優れています。ただし、注意してください――使いすぎると、プログラムが散らかって見えたり、おもちゃのように感じられたりする可能性があります。

例えば、yubikey-agentは、絵文字を使用して出力に構造を加え、単なるテキストの壁にならないようにし、重要な情報に注意を引くために❌を使用しています:

$ yubikey-agent -setup
🔐 The PIN is up to 8 numbers, letters, or symbols. Not just numbers!
❌ The key will be lost if the PIN and PUK are locked after 3 incorrect tries.

Choose a new PIN/PUK: 
Repeat the PIN/PUK: 

🧪 Reticulating splines …

✅ Done! This YubiKey is secured and ready to go.
🤏 When the YubiKey blinks, touch it to authorize the login.

🔑 Here's your new shiny SSH public key:
ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBCEJ/
UwlHnUFXgENO3ifPZd8zoSKMxESxxot4tMgvfXjmRp5G3BGrAnonncE7Aj11pn3SSYgEcrrn2sMyLGpVS0=

💭 Remember: everything breaks, have a backup plan for when this YubiKey does.

デフォルトでは、ソフトウェアの作成者のみが理解できる情報を出力しないでください。 出力の一部が、あなた(開発者)がソフトウェアの動作を理解するのに役立つだけの場合、それは通常のユーザーにはデフォルトで表示されるべきではありません――冗長モードでのみ表示されるべきです。

外部の人々やプロジェクトに新しい人々からユーザビリティのフィードバックを求めましょう。彼らは、あなたがコードに近すぎて気づけない重要な問題を見つけるのに役立つでしょう。

stderrをログファイルのように扱わないでください、少なくともデフォルトでは。 ログレベルラベル(ERR、WARNなど)や余分なコンテキスト情報(冗長モードの場合を除く)を出力しないでください。

大量のテキストを出力する場合は、ページャー(例:less)を使用してください。 例えば、git diffはデフォルトでこれを行います。ページャーの使用はエラーを起こしやすいので、ユーザーの体験を悪化させないように実装に注意してください。ページャーは、stdinまたはstdoutがインタラクティブなターミナルである場合にのみ使用してください。

lessに使用する sensible なオプションセットはless -FIRXです。これは、コンテンツが1画面に収まる場合はページングせず、検索時に大文字小文字を無視し、色とフォーマットを有効にし、lessが終了したときに画面上にコンテンツを残します。

lessにパイプするよりも堅牢なライブラリがあなたの言語にあるかもしれません。例えば、Pythonのpypagerなどです。

エラー

ドキュメントを参照する最も一般的な理由の1つは、エラーを修正するためです。エラーをドキュメントにすることができるなら、それはユーザーの時間を大幅に節約するでしょう。

エラーをキャッチし、人間向けに書き直してください。 エラーが発生することを期待している場合は、それをキャッチし、エラーメッセージを役立つように書き直してください。これは会話のようなものだと考えてください。ユーザーが何か間違ったことをし、プログラムが彼らを正しい方向へ導いているのです。例:「file.txtに書き込めません。chmod +w file.txtを実行して書き込み可能にする必要があるかもしれません。」

信号対ノイズ比が重要です。 無関係な出力を多く生成するほど、ユーザーが何が間違っていたのかを理解するのに時間がかかります。プログラムが同じ種類の複数のエラーを生成する場合、それらを単一の説明ヘッダーの下にグループ化することを検討してください。多くの似たような行を出力するのではなく。

ユーザーが最初にどこを見るかを検討してください。 最も重要な情報を出力の最後に配置してください。目は赤いテキストに引き寄せられるので、意図的かつ控えめに使用してください。

予期しない、または説明不能なエラーが発生した場合は、デバッグ情報とトレースバック情報、およびバグの提出方法に関する指示を提供してください。 それでも、ユーザーを理解できない情報で圧倒しないように、信号対ノイズ比を忘れないでください。デバッグログをターミナルに出力するのではなくファイルに書き込むことを検討してください。

バグレポートの提出を容易にしてください。 できる良いことの1つは、URLを提供し、可能な限り多くの情報を事前に入力することです。

さらに読む: Google: Writing Helpful Error Messages, Nielsen Norman Group: Error-Message Guidelines

引数とフラグ

用語に関する注記:

  • 引数、またはargsは、コマンドの位置パラメータです。例えば、cpに提供するファイルパスは引数です。引数の順序はしばしば重要です:cp foo barはcp bar fooとは異なる意味を持ちます。
  • フラグは名前付きパラメータで、ハイフンと単一文字の名前(-r)または二重ハイフンと複数文字の名前(--recursive)で示されます。ユーザー指定の値を含む場合と含まない場合があります(--file foo.txtまたは--file=foo.txt)。一般的に、フラグの順序はプログラムのセマンティクスに影響しません。

引数よりもフラグを優先してください。 少しタイピングが増えますが、何が起こっているのかがはるかに明確になります。また、将来的に入力の受け入れ方法を変更しやすくなります。引数を使用する場合、既存の動作を壊したり曖昧さを生じさせたりせずに新しい入力を追加することが不可能な場合があります。

引用: 12 Factor CLI Apps。

すべてのフラグにフルレングスのバージョンを持たせてください。 例えば、-hと--helpの両方を持たせてください。フルバージョンを持つことは、冗長で説明的なものにしたいスクリプトに役立ち、フラグの意味をどこでも調べる必要がありません。

引用: GNU Coding Standards。

単一文字のフラグは、一般的に使用されるフラグにのみ使用してください。 特にサブコマンドを使用するトップレベルでは。そうすれば、短いフラグのネームスペースを「汚染」することなく、将来追加するフラグのために複雑な文字や大文字を使用することを強制されなくなります。

複数のファイルに対する単純なアクションには、複数の引数で構いません。 例えば、rm file1.txt file2.txt file3.txt。これはグロビングとも連携します:rm *.txt。

異なるもののために2つ以上の引数がある場合は、おそらく何か間違っています。 例外は、一般的で主要なアクションであり、その簡潔さが記憶する価値がある場合です。例えば、cp <source> <destination>。

引用: 12 Factor CLI Apps。

フラグに標準名がある場合は、それを使用してください。 他の一般的に使用されているコマンドがフラグ名を使用している場合、その既存のパターンに従うのが最善です。そうすれば、ユーザーは2つの異なるオプション(およびそれが適用されるコマンド)を覚える必要がなくなり、ユーザーはヘルプテキストを見なくてもオプションを推測することさえできます。

一般的に使用されるオプションのリストを以下に示します:

  • -a, --all: すべて。例:ps, fetchmail。
  • -d, --debug: デバッグ出力を表示します。
  • -f, --force: 強制。例:rm -fは、権限がないと考えても、ファイルの削除を強制します。これは、通常ユーザー確認を必要とする破壊的なアクションを実行するコマンドにも役立ちますが、スクリプトでその破壊的なアクションを実行したい場合です。
  • --json: JSON出力を表示します。 出力セクションを参照してください。
  • -h, --help: ヘルプ。これはヘルプのみを意味するはずです。 ヘルプセクションを参照してください。
  • -n, --dry-run: ドライラン。コマンドを実行せず、実行された場合に発生する変更を説明します。例:rsync, git add。
  • --no-input: 対話性セクションを参照してください。
  • -o, --output: 出力ファイル。例:sort, gcc。
  • -p, --port: ポート。例:psql, ssh。
  • -q, --quiet: 静か。出力を少なく表示します。これは、スクリプトで実行するときに隠したい人間向けの出力を表示する場合に特に役立ちます。
  • -u, --user: ユーザー。例:ps, ssh。
  • --version: バージョン。
  • -v: これは、冗長またはバージョンのいずれかを意味することがよくあります。冗長には-dを使用し、これにはバージョン、または混乱を避けるために何も使用しないことをお勧めします。

ほとんどのユーザーにとって正しいことをデフォルトにしてください。 設定可能にすることは良いことですが、ほとんどのユーザーは正しいフラグを見つけて常に使用する(またはエイリアスする)ことはありません。デフォルトでない場合、ほとんどのユーザーの体験を悪化させています。

例えば、lsはスクリプトやその他の歴史的な理由を最適化するために簡潔なデフォルト出力を持ちますが、今日設計された場合、おそらくls -lhFがデフォルトになるでしょう。

ユーザー入力のプロンプトを表示してください。 ユーザーが引数またはフラグを渡さなかった場合、それをプロンプトしてください。(参照:対話性)

決してプロンプトを必須にしないでください。 常にフラグまたは引数で入力を渡す方法を提供してください。stdinがインタラクティブなターミナルでない場合は、プロンプトをスキップし、それらのフラグ/引数を必須にしてください。

危険なことをする前に確認してください。 一般的な慣習は、インタラクティブに実行する場合にユーザーにyまたはyesと入力するように促すか、そうでなければ-fまたは--forceを要求することです。

「危険」は主観的な用語であり、危険のレベルは異なります:

  • 軽度: ファイルの削除のような、小さくローカルな変更。確認を求めることも、求めないこともあります。例えば、ユーザーが明示的に「delete」という名前のコマンドを実行している場合、おそらく尋ねる必要はありません。
  • 中程度: ディレクトリの削除のような、より大きなローカル変更、リソースの削除のようなリモート変更、または簡単に元に戻せない複雑な一括変更。通常、ここで確認を求める必要があります。操作の「ドライラン」の方法を提供して、コミットする前に何が起こるかを確認できるようにすることを検討してください。
  • 重度: アプリケーション全体やサーバー全体のような、複雑なものを削除すること。ここで確認を求めるだけでなく、誤って確認するのが難しくする必要があります。削除するものの名前のような、些細ではないものを入力するように求めることを検討してください。代わりに`--confirm=