コメントと組み立て ― 3か月後の自分に向けて書く

導入

スクリプトは「一度書いて終わり」ではなく、半年後に誰かが読んで直すものです。動くだけのスクリプトと、読めるスクリプトの差は、コメントと並べ方で決まります。最初のうちに型を身につけておきましょう。

説明

# から行末まではコメントです（1行目のシバンだけは例外でした）。シェルには「なぜそうするか」を書き残す場所が他にないので、コメントが唯一の説明書になります。

#!/bin/bash
# 日次レポートを作るスクリプト
# 使い方: sh script.sh

# 1. 対象のログを確認する
echo "=== 対象ログ ==="
ls logs

# 2. エラー行だけを数える
echo "=== エラー件数 ==="
grep ERROR logs/app.log | wc -l

良いスクリプトの型は、だいたいこうなっています。

1. シバン（#!/bin/bash）
2. 何をするスクリプトかの説明コメント（使い方も）
3. 設定（変数。第2章）
4. 本体（処理を、区切りコメントつきで上から順に）

コメントで書くべきは「何をしているか」より 「なぜそうしているか」 です。rm -f tmp.txt（一時ファイルを消す）は読めば分かりますが、「前回の残骸があると集計が二重になるため」は書かないと伝わりません。

区切りの echo "=== … ===" も地味に効きます。実行結果が長くなったとき、どこまで進んだかが目で追えるからです。実務のスクリプトは、動いている最中に人が眺めるものでもあります。

行が長くなったら、行末に \ を置いて次の行へ続けられます。パイプでつないだ長い1行を折り返すときによく使います。

やってみよう

上のスクリプトを実行して、=== 対象ログ === と === エラー件数 === の区切りで結果が読みやすくなることを確かめましょう。次に「3. アクセス数を数える」というコメントと wc -l logs/access.log を書き足して、自分でセクションを増やしてみてください。

演習

スクリプトの末尾に、コメント # 3. アクセス数を数える と、logs/access.log の行数を数える処理を書き足して実行してください（行数は 10 です）。