【豆知識】JSONにコメント書けた？JSONCの話と裏技

今日VSCodeでsettings.json編集してたら、普通にコメント書けてることに気づいた。

「あれ？JSONってコメント書けないはずでは...？」って思って調べた内容をまとめます。

✅ 答え：VSCodeが勝手にJSONCという拡張仕様で扱ってた

答えは簡単でした。 VSCodeは特定のJSONファイルを JSONC（JSON with Comments） として自動的に扱ってるだけ。JSONの仕様は変わってません。

🎯 勝手にJSONC扱いされるファイル

• .vscode/settings.json ← これ
• tsconfig.json
• jsconfig.json

❌ ガチのJSONファイル（コメント書いたら死ぬ）

• package.json ← これでやったらエラー
• API通信のJSON
• composer.json

🤔 なぜ混乱したのか？実例で確認

普通のJSONの場合

{
  "port": 3000,  // ❌ これエラーになる
  "host": "localhost"
}

標準のJSONではコメントは書けません。

VSCodeのsettings.jsonの場合

// settings.json
{
  // これは動く！
  "editor.fontSize": 14,
  "editor.tabSize": 2  // 行末コメントもOK
}

VSCodeが自動的にJSONCとして解釈するから動く！

💡 package.jsonにメモ残したい時の裏技

package.jsonは純粋なJSONなのでコメント使えない。でも裏技があります。

方法1：アンダースコアプロパティ（推奨）

{
  "_comment": "このプロジェクトは2025年8月に作成",
  "_memo": "デプロイ時はNODE_ENV=productionを忘れずに",
  "name": "my-awesome-project",
  "version": "1.0.0",
  "scripts": {
    "_scriptsMemo": "build:prodは本番用、要注意",
    "build": "webpack",
    "build:prod": "NODE_ENV=production webpack"
  }
}

方法2：セクションごとにメモフィールド

{
  "name": "my-project",
  "scripts": {
    "test": "jest",
    "test:comment": "jestの設定はjest.config.jsを参照"
  },
  "dependencies": {
    "react": "^18.0.0"
  },
  "dependencies_comment": "reactのバージョンは固定、アップデート時は要検証"
}

方法3：配列内にメモを入れる

{
  "keywords": [
    "nodejs",
    "express",
    "_comment: 以下はSEO用",
    "web-framework",
    "rest-api"
  ]
}

🚀 実践的な使い方

開発時のTODOメモ

{
  "_TODO": [
    "本番デプロイ前にAPI_KEYを環境変数に移動",
    "package-lock.jsonをコミット忘れない",
    "v2.0.0でbreaking changeあり"
  ],
  "name": "my-app",
  "version": "1.9.0"
}

バージョン固定の理由を残す

{
  "dependencies": {
    "lodash": "4.17.20",
    "_lodash_comment": "4.17.21にはバグあり、修正待ち #issue-123"
  }
}

⚠️ 注意点

• アンダースコア始まりは慣習的に「メタ情報」として扱われる
• npm/yarnは基本的に無視してくれる（はず）が、100%の保証はない
• チーム開発時は事前に共有しておく方が安全

まとめ

• VSCodeで動く理由 → JSONC（JSON with Comments）扱い
• package.jsonでは → _comment等の裏技を使う
• 確実にコメント使いたいなら → 最初からYAML使おう

追記：YAMLって素敵ね

# YAMLなら最初からコメント書き放題
name: my-awesome-project
version: 1.0.0

# TODOもメモも自由自在
# デプロイ前にこれやる
scripts:
  build: webpack  # 本番はNODE_ENV=production忘れずに