Ways to Annotate JSON files (e.g. package.json)

Luke Scott August 26, 2019August 27, 2019

Unfortunatley you cannot write comments in JSON files. Here are a couple of workarounds for commenting in JSON files

Comment Inline Next To Source

My favourite solution. Use emoticons (or not). Keeps the notest closest to the source.

{
  "name": "my-package",
  "scripts": {
    "👇 ABOUT-some-command": "Some explanation for command below",
    "some-command": "./scriptA",  
    "some-other-command": "./scriptB",  
    "^ ABOUT-some-other command": "Some explanation for command above",
  }
}

Comments In Same File

The further the comments are from the source the further you have to look. Long comments get messy.

{
  "name": "my-package",
  "scripts": {
    "some-command": "./scriptA",  
  },
  "comments": {
    "scripts": {
      "some-command": "Some explanation for command above",
    }
  }
}

Same Name Markdown File

Have a separate .md file that is the same name as the file but with extension .md. Further away from the source.

my-package
  /package.json
  /package.json.md

Different Markdown File

Harder to remember there are related notes. Further away from the source.

my-package
  /package.json
  /readme.md

Related