YAMLで設定ファイルを書いていると「説明を書き残したい」「一部の設定を一時的に無効にしたい」という場面があります。
そんなときに使うのが「コメントアウト」です。
本記事では、YAMLのコメントの書き方・複数行コメントの方法・記述ルール・注意点をわかりやすく解説していきます。
YAMLを使って設定ファイルを書く方はぜひ最後までご覧ください。
YAMLのコメントアウトの基本的な書き方
それではまず、YAMLのコメントの基本的な書き方について解説していきます。
YAMLでコメントを書くには、「#（シャープ）」記号を使います。
# より後ろの文字はすべてコメントとして扱われ、YAMLパーサーによって無視されます。
【YAMLコメントの基本的な書き方】
# これは行コメントです
name: Tanaka # 行末コメントも可能
age: 30 # 年齢（単位：歳）
# 以下の設定は現在無効化中
# debug: true
このように、行の先頭・行の途中・行末のどこにでも # を書くことでコメントにできます。
JSONにはコメント機能がないため、これはYAMLの大きなメリットのひとつです。
コメントの記述ルールと注意点
YAMLのコメントにはいくつかの記述ルールと注意点があります。
コメントは必ず # から行末まで有効であり、行の途中でコメントを終了させることはできません。
# の前後にスペースを置くことが推奨されますが、必須ではありません。
値の中に # が含まれる場合は、文字列をクォートで囲まないとコメントとして解釈される可能性があります。
【# を文字として使う場合】
color: “#ff0000” # クォートで囲めば # は文字として扱われる
color: #ff0000 # クォートなしだと #ff0000 がコメントになってしまう！
カラーコードなど # を含む値は必ずクォートで囲むことを徹底しましょう。
複数行コメントの書き方
YAMLには複数行にわたるブロックコメントの機能はありません。
複数行のコメントを書く場合は、各行の先頭に # を付ける必要があります。
【複数行コメントの書き方】
# ===================================
# データベース設定
# 本番環境用の設定ファイルです
# 変更前に必ずバックアップを取ること
# ===================================
database:
host: db.example.com
port: 5432
エディタの「複数行を一括でコメントアウト」機能（VSCodeなら Ctrl+/ または Cmd+/）を使えば効率的に複数行をコメントにできます。
設定を一時的に無効化するコメントアウト
設定の一部を一時的に無効にする場合もコメントアウトが使われます。
【設定の一時的な無効化例】
services:
web:
image: nginx
# ports: # 開発環境では一時的にポート公開を無効化
# – “80:80”
コメントアウトを使って設定を無効化することで、設定を完全に削除せずに後から復元しやすい状態を維持できます。
コメントを効果的に活用するためのベストプラクティス
続いては、YAMLのコメントを効果的に活用するためのベストプラクティスを確認していきます。
設定の意図・理由を記録する
コメントには「何をしているか」よりも「なぜそうしているか」を記録することが重要です。
たとえば「timeout: 30 # 外部APIのレスポンス待機時間（秒）。30秒を超えると負荷が問題になるため上限設定」のように、値の意味と理由を記録します。
後から見た人（自分も含む）が設定の意図を理解できるコメントが理想的です。
変更履歴・担当者情報の記録
ファイルの先頭に変更履歴・担当者・目的などを記録するコメントを書く習慣が有用です。
【ファイル先頭のコメントの例】
# ファイル名: production.yaml
# 目的：本番環境のサービス設定
# 最終更新：2024-01-15
# 担当：インフラチーム
# 注意：変更時はステージング環境で確認後にデプロイすること
バージョン管理（Git）と組み合わせることで、さらに変更履歴を管理しやすくなります。
コメントアウトした設定の定期的な整理
コメントアウトした設定が長期間残ったままになると、コードが見づらくなります。
定期的に不要なコメントアウトを削除し、本当に必要なコメントだけを残すメンテナンスが重要です。
「FIXME」「TODO」「NOTE」などのキーワードをコメントに使うことで、後で検索・対応しやすくなります。
ツール・エディタでのコメント活用
続いては、ツールやエディタでのコメント機能の活用を確認していきます。
VSCodeでのYAMLコメントの便利な使い方
VSCodeにはYAML用の拡張機能（YAML by Red Hat）があり、シンタックスハイライト・インデント補完・スキーマ検証が利用できます。
複数行の選択後に Ctrl+/（Mac: Cmd+/）で一括コメントアウトが可能です。
YAMLスキーマを設定することで、コメントと合わせて各キーの意味・型・制約を自動補完で確認できます。
Linterとコメントの関係
yamllintなどのYAML Linterを使うと、コメントの前後にスペースがない場合に警告を出す設定もできます。
チームで統一したスタイルでコメントを書くために、Linterの設定をリポジトリに含めることが推奨されます。
Linterで書き方を統一することで可読性の高い設定ファイルを維持できます。
コメントを含むYAMLのパースについての注意
コメントはYAMLパーサーによって無視されますが、ツールによってはコメントを保持してフォーマット変換する機能を持つものもあります。
たとえば ruamel.yaml（Python）はコメントを保持したままYAMLを読み書きできます。
一般的な yaml.dump などはコメントを失うため、コメントを保持したまま加工したい場合はruamel.yamlなどの特殊なライブラリを使う必要があります。
まとめ
本記事では、YAMLのコメントアウトの書き方・複数行コメントの方法・記述ルール・注意点・ベストプラクティス・エディタの活用まで詳しく解説しました。
YAMLのコメントは # を使って書き、行頭・行末・行中どこでも使えます。複数行コメントは各行に # を付ける必要があります。
# を文字として使う場合はクォートで囲む点に注意が必要です。
コメントを活用することで設定の意図を記録し、後から見ても理解しやすい保守性の高い設定ファイルを作ることができます。
ぜひ本記事を参考に、コメントを使いこなしてYAMLの設定ファイルをより管理しやすくしてみてください。
