YAMLのコメントの書き方を完全マスター【実例付き解説】

KubernetesやDocker、CI/CDツールなどの設定ファイルで使われるYAML形式。

コードを書いていると、「ここに説明を入れておきたいな」「後で見たときのために、メモを残しておこう」と思うことがありますよね。

でも、YAMLのコメントってどう書くんだっけ？複数行のコメントは書けるの？

この記事では、YAMLファイルでのコメントの書き方を、基本から応用まで徹底的に解説していきます。

初めてYAMLを触る方でも、この記事を読めばコメントの書き方がバッチリ分かりますよ。

---

YAMLとコメントの基礎知識

YAMLって何？

YAML（ヤムル）は、設定ファイルやデータを記述するためのフォーマットです。

正式名称は「YAML Ain’t Markup Language（YAMLはマークアップ言語ではない）」という、ちょっとユニークな再帰的頭字語。

特徴

• 人間が読みやすい
• 階層構造をインデント（字下げ）で表現
• JSONよりもシンプルに書ける
• 多くの開発ツールで採用されている

コメントとは

コメントとは、プログラムの動作に影響しない「メモ書き」のことです。

用途

• コードの説明を追加
• 一時的に設定を無効化（コメントアウト）
• TODO や注意事項の記載
• 他の開発者への引き継ぎ情報

プログラムが実行される際、コメント部分は完全に無視されます。だからこそ、自由に説明や覚え書きを入れられるんですね。

YAMLが使われる場面

YAMLは、様々なツールや環境で使われています。

代表的な使用例

• Docker Compose（docker-compose.yml）
• Kubernetes（マニフェストファイル）
• GitHub Actions（ワークフローファイル）
• Ansible（プレイブック）
• CircleCI、Travis CI などのCI/CDツール
• アプリケーションの設定ファイル

これらを使っているなら、YAMLのコメントは必須スキルです。

---

YAMLでコメントを書く基本ルール

シャープ記号（#）を使う

YAMLのコメントは、シャープ記号「#」を使って書きます。

これが唯一のコメント記法です。覚えやすくてシンプルですね。

基本的な書き方

# これがコメントです

シャープ記号から行末までが、すべてコメントとして扱われます。

行の途中からコメントにできる

コメントは、必ずしも行頭から始める必要はありません。

例

name: myapp  # アプリケーション名
version: 1.0  # バージョン番号

データの後ろにスペースを入れて、シャープ記号を書けば、そこからコメントになります。

ちょっとした説明を付け加えたいとき、この書き方がとても便利です。

空白行もコメント扱い

完全に空白の行や、シャープ記号だけの行も有効です。

例

# データベース設定
database:
  host: localhost
  port: 5432

#
# ここからはサーバー設定
#
server:
  port: 8080

視覚的な区切りとして、空白行やシャープ記号だけの行を使うと、ファイルが読みやすくなります。

---

コメントの実践的な使い方

設定項目の説明を追加

最も一般的な使い方が、各設定の意味を説明することです。

例：Docker Composeファイル

version: '3.8'

services:
  web:
    image: nginx:latest
    ports:
      - "80:80"  # ホストの80番ポートをコンテナの80番にマッピング
    volumes:
      - ./html:/usr/share/nginx/html  # ローカルのhtmlディレクトリをマウント
    restart: always  # コンテナが停止したら自動的に再起動

特に、数値やポート番号など、パッと見て分かりにくい設定には説明があると助かります。

セクションの見出しとして使う

長い設定ファイルでは、コメントで見出しを作ると構造が分かりやすくなります。

例：Kubernetes マニフェスト

# ==========================================
# アプリケーションのデプロイメント設定
# ==========================================
apiVersion: apps/v1
kind: Deployment
metadata:
  name: myapp-deployment

# ==========================================
# サービスの公開設定
# ==========================================
---
apiVersion: v1
kind: Service
metadata:
  name: myapp-service

イコール記号や罫線文字を使って、見出しを目立たせるテクニックもよく使われます。

TODO やメモの記入

開発中の覚え書きや、今後の作業予定を残すのにも便利です。

例

# TODO: 本番環境では環境変数から読み込むように変更
database:
  password: "temporary_password"

# NOTE: このタイムアウト値は要調整
timeout: 30

# FIXME: パフォーマンス問題があるため見直しが必要
cache:
  enabled: true
  ttl: 3600

TODO、NOTE、FIXME といったキーワードを使うと、後で検索しやすくなります。

設定の一時的な無効化（コメントアウト）

設定を削除せずに一時的に無効にしたい場合、コメントアウトが活躍します。

例

server:
  port: 8080
  # debug: true  # デバッグモードは本番では無効化
  # log_level: debug  # 本番ではinfoレベルを使用
  log_level: info

設定を残しておきながら無効化できるので、後で簡単に元に戻せます。

---

複数行のコメント

YAMLには複数行コメントの専用記法がない

重要な点として、YAMLには複数行コメント専用の記法がありません。

他のプログラミング言語にあるような /* ... */ のような記法は使えないんです。

各行にシャープ記号を付ける

複数行のコメントを書きたい場合は、各行の先頭にシャープ記号を付けます。

例：詳細な説明

# このアプリケーションは、ユーザー管理システムです。
# 主な機能：
# - ユーザー登録・編集・削除
# - 権限管理
# - ログイン認証
# 
# 開発者: 山田太郎
# 最終更新: 2025-01-15

application:
  name: user-management-system
  version: 2.0.0

少し手間ですが、これが標準的な書き方です。

エディタの機能を活用

多くのエディタには、複数行を一括でコメント化する機能があります。

Visual Studio Code の場合

• Windows/Linux: Ctrl + /
• Mac: Cmd + /

コメントにしたい行を選択して、このショートカットを押すだけ。各行の先頭にシャープ記号が自動的に追加されます。

同じ操作をもう一度すれば、コメントを解除できます。

---

コメントを書くときの注意点

インデントに気を付ける

YAMLはインデントに厳密です。コメントのインデントも、前後の文脈に合わせましょう。

良い例

server:
  # サーバーのポート設定
  port: 8080
  # ホスト名の設定
  host: localhost

避けるべき例

server:
# インデントが合っていない（動作には影響しないが読みにくい）
  port: 8080
    # インデントが深すぎる
  host: localhost

コメント自体は動作に影響しませんが、インデントが揃っていないと読みにくくなります。

文字列の中にシャープ記号を使う場合

文字列の値としてシャープ記号を使いたい場合は、クォートで囲む必要があります。

例

# これはコメント
message: "これは #1 のメッセージです"  # 文字列内のシャープはそのまま
hashtag: '#yaml'  # クォートで囲めば文字列として扱われる

クォートなしで書くと、シャープ以降がコメントと判断されてしまいます。

日本語のコメントも使える

YAMLはUTF-8エンコーディングをサポートしているため、日本語のコメントも問題なく使えます。

例

# データベース設定
# 本番環境では環境変数から取得すること
database:
  host: localhost  # ローカル開発用
  port: 5432  # PostgreSQLの標準ポート
  name: myapp_db  # データベース名

ただし、チーム開発で国際的なメンバーがいる場合は、英語でコメントを書くことを検討しましょう。

コメントだけの行末に余分な空白を残さない

行末の余分な空白は、見えないため気づきにくいバグの原因になることがあります。

多くのエディタには「保存時に行末の空白を削除」という設定があるので、有効にしておくと安心です。

---

ベストプラクティス：良いコメントの書き方

「なぜ」を説明する

コードを見れば「何をしているか」は分かります。コメントでは「なぜそうしているか」を説明しましょう。

悪い例

timeout: 300  # タイムアウトを300秒に設定

これは見れば分かる内容で、コメントの価値がありません。

良い例

timeout: 300  # 大容量ファイルのアップロードに対応するため5分に設定

理由や背景を書くことで、後から見た人が判断できるようになります。

過度なコメントは避ける

すべての行にコメントを付ける必要はありません。自明な内容にコメントは不要です。

過度なコメントの例

# 名前
name: myapp  # アプリケーションの名前
# バージョン
version: 1.0  # バージョンは1.0
# 説明
description: Sample application  # これは説明です

これでは、かえって読みにくくなります。

適切なコメントの例

name: myapp
version: 1.0
description: Sample application  # 本番環境では具体的な説明に変更すること

本当に必要な情報だけをコメントにしましょう。

古いコメントは削除する

古くなったコメント、すでに該当しない情報は、積極的に削除してください。

問題のある例

# 2023年版の設定
# TODO: 2024年に更新予定
database:
  host: new-server.example.com  # 2024年に移行済み

TODOが完了しているのに残っていたり、情報が古いままだと、混乱の元になります。

重要な制約や依存関係を明記

設定を変更する際の注意点や、他の設定との関係を書いておくと親切です。

例

# 警告: この値は環境変数MAX_CONNECTIONSと一致させること
max_connections: 100

# 注意: cache_size を増やす場合は、メモリ使用量が増加します
# 512MB以上のメモリが必要です
cache_size: 1024

---

実践例：実際のYAMLファイル

GitHub Actions のワークフローファイル

# CI/CDワークフロー定義
# プルリクエスト時とmainブランチへのpush時に実行

name: CI Pipeline

# トリガー設定
on:
  push:
    branches:
      - main  # mainブランチへのpushで実行
  pull_request:
    branches:
      - main  # mainブランチへのPRで実行

jobs:
  test:
    # Ubuntu最新版で実行
    runs-on: ubuntu-latest

    steps:
      # リポジトリのチェックアウト
      - uses: actions/checkout@v3

      # Node.js環境のセットアップ
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'  # LTS版を使用
          cache: 'npm'  # 依存関係のキャッシュを有効化

      # 依存関係のインストール
      - name: Install dependencies
        run: npm ci

      # テストの実行
      - name: Run tests
        run: npm test

      # カバレッジレポートの生成
      # - name: Generate coverage
      #   run: npm run coverage
      # TODO: カバレッジ80%達成後に有効化

Kubernetes のマニフェストファイル

# ========================================
# Webアプリケーションのデプロイメント定義
# ========================================

apiVersion: apps/v1
kind: Deployment
metadata:
  name: webapp-deployment
  labels:
    app: webapp
    environment: production

spec:
  # レプリカ数（本番環境は3台構成）
  replicas: 3

  selector:
    matchLabels:
      app: webapp

  template:
    metadata:
      labels:
        app: webapp
        version: v1.2.0

    spec:
      containers:
      - name: webapp
        image: myregistry/webapp:1.2.0

        # コンテナのポート設定
        ports:
        - containerPort: 8080
          name: http
          protocol: TCP

        # 環境変数
        env:
        - name: DATABASE_HOST
          value: "db.example.com"
        - name: LOG_LEVEL
          value: "info"  # 本番環境ではinfo、開発環境ではdebugを使用

        # リソース制限
        resources:
          requests:
            memory: "256Mi"  # 最小メモリ要求
            cpu: "100m"      # 最小CPU要求
          limits:
            memory: "512Mi"  # 最大メモリ制限
            cpu: "500m"      # 最大CPU制限

        # ヘルスチェック設定
        livenessProbe:
          httpGet:
            path: /health
            port: 8080
          initialDelaySeconds: 30  # 起動後30秒待機
          periodSeconds: 10         # 10秒ごとにチェック

        readinessProbe:
          httpGet:
            path: /ready
            port: 8080
          initialDelaySeconds: 10
          periodSeconds: 5

---

コメントに関するよくある質問

複数行コメントの記法は本当にないの？

はい、YAMLの仕様には複数行コメント専用の記法はありません。

各行にシャープ記号を付けるのが唯一の方法です。これはYAMLの設計思想で、シンプルさを保つための選択とされています。

コメント内に特殊文字を使っても大丈夫？

大丈夫です。コメント部分は完全に無視されるため、どんな文字を使っても問題ありません。

# 特殊文字も使えます: !@#$%^&*(){}[]|\:;"'<>?,./~`
# 絵文字も使えます: 🎉 🚀 ✨

ただし、チーム開発では過度な装飾は避け、シンプルに保つのが無難です。

YAMLパーサーによって違いはある？

基本的なコメント記法（シャープ記号）は、すべてのYAMLパーサーで共通です。

ただし、一部のツールには独自の拡張機能がある場合があります。標準的な記法を使っていれば、互換性の問題は起きません。

コメントはパフォーマンスに影響する？

影響しません。YAMLファイルを解析する際、コメントは最初の段階で除去されます。

コメントをたくさん書いても、実行速度やメモリ使用量に変化はありません。遠慮せず、必要なコメントを追加してください。

---

エディタとツールでのコメント対応

Visual Studio Code

VS Code は YAML ファイルを標準でサポートしています。

便利な機能

• シンタックスハイライト（コメントが灰色で表示）
• Ctrl + /（Mac: Cmd + /）で一括コメント化
• YAML拡張機能でバリデーション

拡張機能「YAML」をインストールすると、より高度なサポートが受けられます。

IntelliJ IDEA / PyCharm

JetBrains製のIDEも、優れたYAMLサポートを持っています。

便利な機能

• インテリジェントな補完
• Ctrl + /でコメント切り替え
• 構文チェックとエラー表示
• フォーマット自動整形

オンラインツール

ブラウザ上でYAMLを検証できるツールもあります。

YAML Lint
文法チェックができるWebサービス。コメント付きのYAMLファイルも正しく解析できます。

yamllint
コマンドラインツール。コメントのスタイルチェックも可能です。

# インストール（Python環境）
pip install yamllint

# ファイルのチェック
yamllint config.yaml

---

まとめ：コメントでYAMLファイルを分かりやすく

YAMLファイルでのコメントの書き方について、基本から実践まで解説してきました。

この記事のポイント

• YAMLのコメントはシャープ記号（#）で書く
• 行頭でも行の途中でもコメントにできる
• 複数行コメントは各行にシャープを付ける
• 「なぜ」を説明し、過度なコメントは避ける
• エディタの機能を活用すると効率的

コメントは、未来の自分や他の開発者への思いやりです。

3ヶ月後に自分が見たとき、「あのときの自分、ありがとう！」と思えるようなコメントを書きましょう。

設定ファイルは一度書いたら終わりではなく、メンテナンスが続きます。適切なコメントがあれば、変更や拡張がずっと楽になりますよ。

この知識を活かして、読みやすく保守しやすいYAMLファイルを作成してくださいね！