シェルスクリプトではコードの意図や処理内容を明確にするために コメントアウト を使います。 コメントは単なるメモではなく、保守性や品質を高めるための重要な技術です。
この記事ではコメントアウトの使い方を解説します。
コメントアウトとは？
シェルスクリプトでは # を付けるとその行はコメントになり、シェルが無視します。
# これはコメントです
echo "Hello"VSCodeではショートカットが用意されており、「Ctrl + /（Windows）、 」で簡単にコメントアウトできます。Cmd + /(Mac)
コマンドを直接説明する場合は、そのコマンドの後ろに書くこともあります。
この場合、#より後ろはコメントと見做されます。
echo "$LINENO" # 行番号を表示コメントの役割として、
- 意図の共有：なぜこの処理が必要なのか
- 保守性向上：後から自分や他人がコードを読みやすくなる
- 事故防止：重大な影響を与える処理に注意書きを残せる
などが挙げられます。
ヘッダーを追加する
シェルスクリプトの1行目にはshebangを記載しますが、次に ヘッダーコメント を書くのが一般的です。 目的は「このスクリプトが何をするものか」を自分だけではなく、チームメンバーと共有するためです。
ヘッダーの基本は5W（When / Who / What / Why / Where）で、以下のように記載します。
#!/usr/bin/env bash
# ============================================
# 担当者 : 山田太郎
# スクリプト名 : PostgreSQL のバックアップ取得
# 目的 : 手動作業のミス防止と定期バックアップの自動化
# 対象 : /var/lib/postgresql/data
# 作成日 : 2026-01-28 Ver.1 新規作成
# 更新履歴 : 2026-03-10 Ver.2 〇〇処理を追加
# : 2026-04-15 Ver.3 〇〇処理を〇〇に変更
# ============================================経験的に更新履歴は下に伸びていくので、ヘッダーの最後に記載してあることが多いです。
特に「目的や概要」にWhy（なぜ）が書いてあると品質が一段上がります。
処理ごとのコメントの書き方
スクリプト内の各処理にもコメントを付けます。
ポイントは 「処理をそのまま記述する」のではなく「なぜ必要か」を書くことです。
❌ 悪い例（コードをそのまま説明している）
# dataディレクトリをtarで圧縮
tar -czf backup.tar.gz /var/lib/postgresql/data✔ 良い例（コードの意図が分かる）
# PostgreSQL停止後、復旧用としてデータディレクトリ全体をバックアップ
tar -czf backup.tar.gz /var/lib/postgresql/data処理が多い場合は、ブロック単位でコメントを書くと読みやすくなります。
# --------------------------------------------
# Step1: 古いバックアップを削除（保持期間は7日）
# --------------------------------------------
find /backup -mtime +7 -delete変数や定数の意味を明確にする場合も有効です。
# バックアップ保持日数
RETENTION_DAYS=7詳細なタスク管理は Git（Issue / Pull Request）等で行うのが実務的ですが、TODO / FIXME等のアノテーションコメントも併用できます。
# TODO: エラー時のリトライ処理を追加する
# FIXME: 一時ディレクトリのパスを環境変数化するVSCodeの拡張機能Todo Treeを使うと、アノテーションコメントを一覧で確認できて便利です。
なお、実施済みのTODOや修正済みのFIXMEはコードが汚れるため、最終的に削除しましょう。
コメント