YAMLコメントとJSON変換

コメントはJSONとYAMLの最も大きな違いの一つです。YAMLは # 文字を使ったコメントを完全にサポートしていますが、JSONにはコメント構文がまったくありません。このため、インラインドキュメントが必要な設定ファイルにはYAMLがはるかに適しています。

コメント付きのYAML：

# Database configuration
database:
  host: localhost       # Primary database host
  port: 5432           # Default PostgreSQL port
  name: myapp_prod     # Production database name
  # Connection pool settings
  pool:
    min: 5             # Minimum connections
    max: 20            # Maximum connections
    # Idle timeout in milliseconds
    idle_timeout: 30000

JSONに変換するとすべてのコメントが削除される：

{
  "database": {
    "host": "localhost",
    "port": 5432,
    "name": "myapp_prod",
    "pool": {
      "min": 5,
      "max": 20,
      "idle_timeout": 30000
    }
  }
}

これは不可逆です。 JSONに変換されると、コメントは復元できません。そのJSONをYAMLに戻しても、元のドキュメントなしの有効なYAMLが生成されます。

ドキュメントを保持するための戦略：

1. YAMLを信頼できる唯一の情報源として維持。 コメントが重要な場合、YAMLファイルを正規バージョンとして保持し、必要に応じてそこからJSONを生成します。
2. 説明フィールドを使用。 ドキュメントをデータ値として追加："_comment": "This explains the setting"。ただし、構造に余分なデータが追加されます。
3. 外部ドキュメント。 設定を文書化する別のREADMEまたはスキーマファイルを維持します。

JSON with Comments (JSONC)： 一部のツールは // と /* */ コメントを許可するJSONC（JSON with Comments）をサポートしています。TypeScriptの tsconfig.json やVS Codeの settings.json がこの形式を使用しています。ただし、JSONCは標準JSONではなく、ほとんどのパーサーは拒否します。

YAMLでのコメント配置：

# 行全体のコメント
key: value  # インラインコメント（#の前にスペースが必要）
# key: old_value  # コメントアウトされた設定

コメントは設定値が何であるかだけでなく、なぜその値が選ばれたかを説明するために非常に有用です。