一部を置き換えるチュートリアルの難しさ

チュートリアルに書いてあるとおりに操作しているのに、
期待通りに動かなかったりすることがよくあると思いますが、
動かない原因の多くは、入力する内容を少し間違えてしまうことです。

たとえば、チュートリアルに bash シェルから入力する操作が

$ az group create --name <myResource> --location <myLocation>

のように書かれているとき、
<myResource> の部分を新しく作成するリソースグループの名前に置き換え、
<myLocation> の部分をリソースを配置する地域名に置き換えて

az group create --name myTrial --location japaneast

と入力します。

この置き換える部分を「プレースホルダー」と呼びます。

そして、次に入力する操作が

$ az appservice plan create --name <planName> --resource-group <myResource> --sku FREE --is-linux

と書かれているときは、前に入力した内容と整合をとって

az appservice plan create --name my-free-plan --resource-group myTrial --sku FREE --is-linux

と入力します。もし、

az appservice plan create --name my-free-plan --resource-group yourTrial --sku FREE --is-linux

のように整合が取れていない値（yourTrial）を入力してしまうと
チュートリアルは期待通りに動きません。

Response, Resource, Resume など似たスペルがあるプレースホルダーが
使われているときは、スペルにも注意が必要になります。

○○でもわかる！ような具体的な説明になっていたとしても
整合性を取るために頭の中でいろいろ考えることが多く難しくなってしまうのですね。

実際に入力する内容に置き換えてから実際に操作する

少し作業内容を工夫をしてみましょう。
あらかじめ実際に入力する内容に置き換えたコマンドを書くことです。

もし、

$ az group create --name <myResource> --location <myLocation>

のようにチュートリアルに書かれていたら、新しいテキストファイルなどに

az group create --name myTrial --location japaneast

と書いておきます。
そして、書いた内容をコピペすることでシェルに入力します。

この作業により頭の中だけでなく目で見ることができ、
１つ１つ冷静にプレースホルダーを置き換えることができるようになります。

チュートリアルや手順書がテキストファイルなら、
テキストエディターの機能ですべて置き換える
ことができ、何も考えずにコピペを繰り返すだけの単純作業になります。
これはかなり楽です。

ちなみに、Web に書かれたチュートリアルの中には自動的に置き換えて表示されているものも
登場しておりすごいと思ったのですが、まだ多くはありません。
また、そのチュートリアルの中でしか置き換えられません。

様々なプレースホルダーの問題点

プレースホルダーの書式はチュートリアルによってそれぞれ異なります。
それぞれの特徴を挙げてみましょう。代表的なのはこれらでしょう。

サンプル	書式
<placeHolder>	山カッコ
placeHolder	イタリック
${placeHolder}	シェル変数
PLACE_HOLDER	大文字のみ

山カッコは HTML や XML の書き方と同じです。
標準的なのですが、この書き方では HTML や Markdown のソースに書くと
タグに認識されて消えてしまうという問題があります。
<placeHolder> に置き換えれば表示はできるのですが
編集するのが大変です。
また、HTML のサンプルにこの書式のプレースホルダーを書くと
HTML タグとの区別がつきません。

イタリックは多くのチュートリアルで見られるのですが、
プレースホルダーの部分かそうでない部分かを識別することが少し難しいです。
また、この書き方ではテキストファイルで表現することができません。

シェル変数の書式はシェルスクリプトの書き方と同じですが、
それゆえにシェルスクリプトのサンプルに使うことができません。
変数なのかプレースホルダーなのかの区別がつかないからです。
あわよくばシェルスクリプトに使えそうに思えますが、
シェルスクリプトにした場合、実際に入力する値が分かりにくくなります。
事前に変数への代入もしなければなりません。
シェルスクリプトだからそのまま実行できるように思えますが、
ステップ実行することが難しいという問題もあります。

大文字のみの部分をプレースホルダーにしているチュートリアルも見たことがありますが、
これは論外でしょう。
頭字語と客観的に区別することができません。
グローバルなスコープの定数にこのスタイルが採用されているために
コードに使えません。
（最近はグローバル定数でこのスタイルが採用されることが少なくなりましたが）

プレースホルダーはアンダーバー２つで囲むとよい

最も便利なプレースホルダーの書き方は、アンダーバー２つで囲むことです。

サンプル	書式
＿placeHolder＿	アンダーバー

私がこの書き方を初めて見たのは、（意味はプレースホルダーではありませんが）
Python の＿init＿
です。 Markdown での太字の書き方でもあります。

この書き方をチュートリアルや手順書のプレースホルダーに採用したら
多くのメリットが見えてきたので紹介いたします。

（Qiitaでは _ が使えないため本記事ではアンダーバー２つを全角アンダーバーで書いています）

HTML や Markdown にそのまま貼り付けられる

アンダーバー２つで囲む書き方の１つ目のいいことは、
HTML に書き換えるときにそのまま使えることです。

山カッコの場合、前述のような問題がありますが、
アンダーバー２つで囲む書き方であれば、
< > に置き換える必要はありません。
また、HTML のサンプルに使うこともできます。

Markdown に書き換えるときはアンダーバーではなく太字に変わります。
これは問題があるように思うかもしれませんが、
コードやコマンドの中で太字を使うことはないので実質問題ありません。

識別しやすい、見つけやすい

アンダーバー２つで囲む表現にすると、
山カッコやイタリックやシェル変数に比べて幅をとるためか、
速読したときでもプレースホルダーであるかそうでないかを識別しやすくなります。

サンプル	説明
<placeHolder>	山カッコ
placeHolder	イタリック
PLACE_HOLDER	大文字のみ
＿placeHolder＿	アンダーバー
${placeHolder}	シェル変数

識別しやすいことは重要です。
コマンドを実際に入力する直前に
置き換えなければならない部分が残っていないかを
目視でチェックすることがよくあるからです。

また、テキストエディターの検索機能でアンダーバー２つを検索することで
置き換えなければならない部分を確実に見つけることができます。

Markdown のエディターを使った場合、太字になる部分の色が変わるため
見つけやすくなります。

ダブルクリック１発で選択して置き換えられる

ダブルクリック１発で選択できると、

置き換える部分をダブルクリック ⇒ Ctrl + V ⇒
置き換える部分をダブルクリック ⇒ Ctrl + V ⇒ ……

という単純作業になります。
これは楽です。

ところで、ハイフンを単語の区切りにするケバブスタイル（例：my-resource）のシンボルは、
マイナスと区別できないために、ダブルクリック１発で選択できません。
my-resource の my の部分だけ選択されるか resource の部分だけ選択されます。
なので私はケバブスタイルは大嫌いです。
将来ケバブスタイルでもダブルクリック１発で選択できる
機能をエディターやシェルで登場してほしいものです。

山カッコとシェル変数は、これと同じ原因でダブルクリックしてもカッコは選択されません。
ダブルクリックするとカッコの中だけ選択されてしまいます。
置き換える範囲を１文字単位で正確にドラッグしなければならなくなり、
精神力が削られます。

エラーによって早く問題が分かる

プレースホルダーになっている部分は英数字しか使えないなどの
「シンボル」であることが多いのですが、
そのシンボルの先頭にはアンダーバーが付いたシンボルが使えない
ことが多いようです。
Lintなどのスタイルチェックを通せば警告される可能性も高いです。

エラーになれば置き換え忘れたという問題がすぐに分かります。

まとめ

プレースホルダーをアンダーバー２つで囲んだときのメリットを以下にまとめました。
ぜひ試してみてはいかがでしょうか。

HTML や Markdown にそのまま貼り付けられる
識別しやすい、見つけやすい
ダブルクリック１発で選択して置き換えられる
エラーによって早く問題が分かる