Bashスクリプトでは、引用されていない位置で「単語の先頭」に現れる#から行末までがコメントです。基本は一行ずつ# 理由と書きます。コメントは処理内容の言い換えではなく、なぜこの条件/順序/例外が必要か、入力・出力・副作用・失敗時の扱いを残します。先頭の#!はBashから見ればコメント形式でも、実行時にはOSがインタープリター指定として使う特別な行です。複数行をhere-documentで「コメントアウト」する方法は実際には:コマンドへの入力であり、展開や区切りの落とし穴があるため、通常は各行へ#を付けます。
#がコメントになる正確な位置
非対話Bashでは、行頭、引用されていない空白の後、または演算子の後で始まる単語の#がコメントを開始し、残りの文字が無視されます。echo value # 説明は説明がコメントですが、echo value#suffixの#は単語途中なので文字の一部です。
echo "# not comment"の#は引用内の文字です。$#は位置引数の個数を表す特殊パラメーターで、コメントではありません。色コードやURLフラグメントなど#をデータとして使うなら引用します。構文ハイライトだけを信じず、Bashのトークン規則で判断します。
先頭行のshebangはコメント以上の役割を持つ
実行可能スクリプトの先頭が#!/bin/bashなら、多くのUnix系OSは/bin/bashをインタープリターとして使います。#!/usr/bin/env bashはPATH上で最初のbashを探します。前者は場所を固定、後者は配置へ柔軟ですがPATHの信頼性が必要です。運用環境と脅威モデルで選びます。
shebangの前に空行や説明コメントを置くとOSが認識できません。Bash固有の配列や[[ ]]を使うのに#!/bin/shと書かず、実際の言語を明示します。インタープリター行の引数分割はOS差があるため、複数引数を詰め込みません。
ファイルヘッダーは目的と契約を書く
冒頭コメントには、目的、対象環境、入力、出力、副作用、必要権限、外部コマンド、終了状態、所有者、変更手順を短く書きます。「バックアップする」だけでなく、どのディレクトリを読み、どこへ新規出力し、元を変更しないかを明記します。例示値は架空のものにします。
実装と重複する長い手順書を丸写しせず、正式Runbookやチケットの安定した識別子を記載します。リンク切れに備え、スクリプト単体で最低限の安全条件が分かるようにします。版番号や日付を手作業で二重管理して陳腐化させず、VCS履歴とリリース情報を正にします。
コメントはwhatよりwhyと不変条件を書く
# ファイルをコピーの直下にcpがあるだけでは価値が小さいです。# 入力を保持するため新規名へ出力し、検証前は置換しないなら設計理由を伝えます。順序依存、API制限、再試行上限、ロック理由、タイムゾーン、文字コードなど、コードから読み取りにくい制約を残します。
コメントとコードが矛盾したらコードの実挙動が勝つため、変更時は同じレビューで更新します。古い理由が不要になったら削除し、新しい理由を記録します。「絶対変更禁止」のような説明不能な警告ではなく、壊れる条件、検証方法、担当者を具体化します。
関数コメントは引数・出力・副作用を示す
関数の直前に、引数の意味/許可形式、標準出力、標準エラー、return値、変更するファイル/変数、呼び出し前提を書きます。Bash関数は現在のシェルコンテキストで実行され、新しいプロセスではないため、グローバル変数、作業ディレクトリ、umask、trapの変更が呼び出し元へ残り得ます。
例として「引数1は既存通常ファイル、標準出力へSHA-256、0=成功、64=使用法誤り、ファイルは変更しない」と契約化します。コード側でも引数数$#と型を検証します。コメントだけで安全を保証せず、テストで正常/境界/失敗/空白入りパスを確認します。
未完了メモ・FIXME・WARNINGを追跡可能にする
# 未完了メモ(owner, 2026-08-01, ISSUE-123): ...のように、責任者、期限または見直し条件、追跡ID、完了条件を添えます。「後で直す」だけの未完了メモを放置しません。WARNINGは実際の危険、影響範囲、安全な代替、承認手順を記載します。
コメントにパスワード、APIトークン、個人情報、本番ホスト一覧、過去の秘密を残しません。コメントアウトしてもVCS履歴や配布物に残ります。漏えい時は文字列削除だけでなく秘密を失効/ローテーションし、履歴修正は組織手順で行います。
一時無効化は各行#か版管理を使う
短い範囲はエディターで各行へ#を付けます。長期間不要なコードはコメント塊として残さずVCS履歴へ任せて削除します。死んだコードは古いライブラリ、危険なコマンド、秘密、誤った手順を温存し、検索結果とレビューを妨げます。
条件付き無効化が機能要件ならコメントではなく、明示的な設定フラグとデフォルト、監査ログ、テストを設計します。if false; then ... fiも構文解析され、将来誤って有効化されるため、一時デバッグに限定し追跡IDを付けます。
here-documentは複数行コメント専用構文ではない
よく見る: <<'COMMENT'は、no-opの:コマンドへhere-documentを入力する構文です。引用した区切りなら本文の変数展開、コマンド置換、算術展開は抑止されますが、これはBashのコメント構文ではありません。区切り行は余計な空白なしで一致する必要があります。
区切りを引用しないと$(command)などが展開され、コメントのつもりで副作用を起こし得ます。本文中に同じ区切りが現れる、インデントが変わる、別シェルで挙動が違う問題もあります。文書用here-docなど本来の入力用途以外は各行#を優先します。
: と引用文字列もコメントではない
: '複数行...'は:へ一つの文字列引数を渡すコマンドです。本文に単一引用符が現れると引用が終了し、予期せぬシェルコードになり得ます。パラメーター展開を伴う: "..."も展開自体は実行されます。コメント代替として使いません。
単純な一行注釈は#、ユーザーへ表示する説明はprintf、コマンドへ渡す複数行データは引用したhere-doc、と目的を分けます。構文を巧妙にして行数を減らすより、読者が実行/非実行を即判断できる形式を選びます。
コメント内のコマンド例も安全に保つ
運用例として再帰的かつ強制的な削除コマンド、curl | sh、秘密入りURL、全権限付与をコメントへ残すと、利用者がコピー実行する危険があります。例は読み取り確認から始め、プレースホルダーを明確にし、本番対象を含めません。破壊的手順はRunbookで承認、バックアップ、dry-run、ロールバックと一緒に管理します。
古い回避策を「念のため」残さず、なぜ廃止したかをチケットへ記録してコードから除きます。コメントのURLやコマンドもレビュー対象にし、ドメイン、HTTPS、版、対象環境を確認します。
bash -nとテストでコメント変更を確認する
変更後はbash -n -- script.shで読み取り/構文検査します。-nはコマンドを実行せず構文を読むため、引用やhere-docの閉じ忘れを見つけられます。ただし未定義変数、実行時権限、外部コマンド失敗、危険な対象選択までは検証しません。
次に隔離したテストデータ、非特権ユーザー、ネットワークなし等で実行し、終了状態と副作用を確認します。コメントだけの変更でも、shebang位置、行継続のバックスラッシュ、here-doc区切り、引用内#へ触れると挙動が変わり得ます。差分レビューと自動テストを省略しません。
レビュー時にコメントの品質を点検する
コードと一致するか、理由/制約を説明するか、秘密を含まないか、期限切れ未完了メモがないか、危険例が独り歩きしないかを確認します。コメント密度を目標にせず、複雑なコードを説明で正当化する前に関数分割、変数名、入力検証を改善します。
運用事故後は「注意コメントを増やす」だけで終えず、危険操作のデフォルト無効、承認、dry-run、対象上限、バックアップ、監視をコード/仕組みへ実装します。コメントは最後の説明層であり、安全制御そのものではありません。
確認チェックリスト
- #が単語先頭でコメントになる規則を理解した
- shebangを必ず1行目に置き実際のインタープリターを指定した
- whatではなくwhy・制約・副作用を書いた
- 関数の引数/出力/終了状態/変更対象を記載した
- 未完了メモへ責任者・期限/条件・追跡IDを付けた
- 秘密や危険なコピー用コマンドをコメントへ残していない
- here-docや:文字列を真のコメントと誤解していない
- bash -n・差分レビュー・隔離テストを実施した
コメント