JSONファイルのコメント

標準JSONは、いかなる形式のコメントもサポートしていません。シングルラインコメント（//）、ブロックコメント（/* */）、ハッシュコメント（#）のいずれの構文も存在しません。JSONドキュメントにコメントを含めようとすると、準拠するすべてのJSONパーサーでパースエラーが発生します。

JSONがコメントを除外した理由:

JSONの生みの親であるDouglas Crockfordは、コメントがパースディレクティブとして使用されることを防ぐためにJSONからコメントを除去したと説明しています。それによりフォーマットが分断され、相互運用性が低下するのを避けるためです。彼の設計思想は、JSONはデータ交換形式であり、ソースコード形式ではないということでした。システム間で交換されるデータには人間のアノテーションは不要であり、スキーマとドキュメントがその役割を果たすべきだとしています。

開発者のフラストレーション:

この設計上の判断は、JSONの最も議論されている側面の一つです。package.json、tsconfig.json、.eslintrc.json などの設定ファイルは人間が作成・保守するものであり、特定の設定が存在する理由の説明、非推奨オプションのドキュメント化、TODOメモの記載ができないことは、生産性に実質的な影響を与えます。このフラストレーションが、コメントをサポートする代替形式の誕生につながりました。

回避策: _comment キー規約:

一部の開発者は慣例的なキー名を使ってドキュメントを追加しています:

{
  "_comment": "Timeout is in milliseconds",
  "timeout": 5000
}

これは技術的に有効なJSONです。キーは単なる通常の文字列プロパティだからです。ただし、これはデータモデルを汚染し、JSONを利用するアプリケーションがこれらのキーを無視しなければ予期しない動作を引き起こす可能性があります。

コメントをサポートする代替形式:

• JSONC: // と /* */ コメントおよび末尾カンマを許可します。VS Code、TypeScript、その他のMicrosoftツールで使用されています。
• JSON5: コメント、末尾カンマ、クォートなしのキー、シングルクォートの文字列などを許可する、より広範なスーパーセットです。
• YAML: # によるコメントをサポートし、JSONの制限が厳しすぎる設定によく使用される、まったく異なる形式です。
• TOML: コメントサポートを持つもうひとつの設定形式で、Rust（Cargo.toml）やPython（pyproject.toml）で使用されています。

開発者がよくやるミス:

最も多いミスは、標準JSONファイルに // コメントを追加し、パーサーが失敗した際に混乱することです。もうひとつのミスは、コメントを除去する前処理ステップで、文字列値内のコメントに似たシーケンス（例: "url": "https://example.com" には文字列内に // が含まれる）の処理に失敗するエッジケースです。正規表現ベースの除去ではなく、専用のJSONCパーサーを必ず使用してください。

ベストプラクティス:

使用するツールがJSONCをサポートしている場合は、それを使用し、可能であればファイル拡張子を .jsonc にしてください。厳密なJSONの場合は、別のファイルにドキュメントを保持するか、説明的なキー名を使用しましょう。標準パーサーで利用されるJSONファイルには決してコメントを追加しないでください。