TOMLコメントとJSON変換

YAMLと同様にTOMLはコメントをサポートします。JSONと同様にJSONにはコメント構文がまったくありません。この根本的な違いにより、TOMLからJSONへの変換は常にコメントを失います。これがチームが設定ファイルにTOMLを好む主な理由の一つです。

コメント付きTOML：

# Application settings
[app]
name = "my-service"       # Display name in the dashboard
version = "1.0.0"         # Follows semver

# Server configuration
[server]
host = "0.0.0.0"          # Bind to all interfaces
port = 8080               # Default HTTP port
# port = 443              # Uncomment for HTTPS

# Database connection
[database]
url = "postgres://localhost/mydb"
# WARNING: Change this password in production!
pool_size = 10             # Max concurrent connections

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

{
  "app": {
    "name": "my-service",
    "version": "1.0.0"
  },
  "server": {
    "host": "0.0.0.0",
    "port": 8080
  },
  "database": {
    "url": "postgres://localhost/mydb",
    "pool_size": 10
  }
}

これは不可逆です。 データベースパスワードに関する重要なWARNINGを含むコメントは永久に失われます。JSONをTOMLに戻しても、ドキュメントなしの有効なTOMLが生成されます。

TOMLコメント構文：

# 行全体のコメント
key = "value"  # インラインコメント（値の後）

# コメントは以下の場所に配置可能：
# - 独立した行
# - 同じ行の値の後
# - 文字列の中はNG（クォート内の#はリテラル）

message = "Use # for comments"  # これはコメント。文字列内の#はリテラル

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

1. TOMLを信頼できる唯一の情報源として維持。 必要に応じてTOMLからJSONを生成しますが、常にTOMLファイルを編集します。これにより人間の読者向けにコメントが保持されます。
2. 説明フィールドを使用。 ドキュメントをデータとして追加：description = "Max concurrent database connections"。変換後も残りますが、構造にデータが追加されます。
3. JSON Schema。 各設定キーを文書化する description フィールドを持つJSON Schemaを定義します。このアプローチはドキュメントとデータを分離します。
4. コメントアウトされた設定。 TOMLでは開発者が代替値をコメントアウトすることが一般的です。このパターンにはJSON等価物がなく、変換時に失われます。

他の形式との比較：

• YAML：# コメントをサポート（JSONへの変換時に失われる）
• JSON：コメントなし（JSONCは非標準）
• TOML：# コメントをサポート（JSONへの変換時に失われる）

TOMLコメントは、人間が編集する設定ファイルにJSONよりTOMLを使用する最も強力な理由の一つです。