Answer a question

I'm working through a project that's in progress, and I'm making notes within the files to explain the purpose of existing code. One of the things I noticed is that VS Code allows (and even comes with) comments for JSON files within the .vscode folder. Here's .vscode/extensions.json.

But if I try to add comments in JSON files elsewhere, I'm told that comments aren't allowed.

I understand how to fix this with a custom setting, but is this basically Microsoft breaking the rules and allowing comments in JSON it's going to read from even though JSON doesn't allow comments, but enforcing the comment ban in files that it isn't going to read from?

And, since while Microsoft may allow comments in JSON they're reading, whoever's reading other JSON configuration files may not, I assume I should just stay away from them outside of .vscode?

Answers

---

VSC Supports Comments in Every JSON-File That is Configured to have Comment Support

---

Comment support in JSON files isn't contingent on file location, or pathname semantics, but instead on the Parser that it is being parsed by (More on parsers in bit). Supporting Comments in JSON is far from unique to VSCode, and certainly isn't unique to the VSCode directory ./.vscode/. Comment support in JSON is a feature included with VSCode, and is usable without 3rd Party software, extensions or any other form of extendable-software. I often write comments in my eslintrc.json, which is supported without any non-default configuring. Another JSON file that supports comments, which I take advantage of when I am working in one, VSCode's Theme JSON-Files, a file used by VS-Code Extensions & Themes, located in the ".../user/vscode/extensions/<some-theme-name>/themes/<some-theme-name>.json" (<-- remember when you read pathnames that I am a Linux guy).

VSCode also does something else you might notice, and it does it using the same concept that it uses to support comments in JSON files. VS-Code will occasionally treat a non-JSON file, as if it were a JSON file. It does this with .prettierrc,, .babelrc, and many others. By supporting the Dot-.(*.)rc config files as JSON, they can be formatted as if they were JSON..

ECMA-404

Because JSON is an Open Standard, there are many different implementations of the text-based syntax. Some comply completely with the ECMA-404 standardization, others only partially comply, however, partial representations of the ECMA JSON Standard, are often still refereed to as JSON with in the Dev-Community. The main reason some project, and/or company, doesn't fully comply with the JSON standard is to add functionality, or semantics to the Syntax.

If it were not for JSON being an Open-Standard, VS-code would likely not be legally allowed to create custom representations of JSON. Its only because JSON is an ECMA standard the VSCode is able to do this. Which is why JSON, ECMA, and VSCode or so awesome, they use tools and resources available to all people.

This is how VSCode Supports Comments in its JSON files:

Usually when functionality is added to a JSON representation the representation will take on a unique name, which is almost always the same as its file extension (which is also new and unique). Real world examples of this are (JSONC & JSON5). The reason for adding a new extension stems from the need to have more than one type of JSON parser for processing JSON files. VSCode needs to be able to parse Standard JSON, and as you know it parses JSONC (JSON W/ Comments), so the editor has to implement the following 2 parsers:

#1 JSON

The first parser JSON is a standardized JSON parser that conforms 100% to the standardization implemented by the ECMA-404(2017) document. The JSON parser parses all files in VSCode that end with the .json file extension (unless instructed not to by the editors configuration). This parser throws an Error when it attempts to parse a comment.

#2 JSONC

The second parser is JSONC (JSON W/ Comments). It is responsible for parsing all files that use the .jsonc file extension. This is considered to be a non-conformant JSON (processor/parser) parser, however, this parser does support comments.

Configure VS-Codes JSON parser to parse the JSON as JSONC

---

    //  FILE: "./.vscode/settings.json"
   
    // Example A
    "files.associations": {
        "*.json": "jsonc"
    },

    // Example B
    "files.associations": {
        "file-name-here.json": "jsonc" 
    }

---

The above example demonstrates what is, IMO, the best way to add support for comments in a JSON file that you use with VSCode.

---

1. Example A

Example A, Declares JSON files as being associated with the JSONC file-type. This tells VS-Code to use the JSONC parser to parse JSON files.

2. Example B

Example B declares a specific file as being associated with the JSONC file-type. Just like in Example A, VS-Code now knows to parse that file using the JSONC parser.

---

These Images Demonstrate the use of "files.associations": {...} in a before & after image pair.

You can use the setting...

"files.associations": {...}

...for a whole list of different uses. One such use is to add JSON support to a file that doesn't use the .json ext but implements the standard JSON Syntax. Most use-cases for `"files.associations" is for non-JSON stuff. Its a really good tool to know for anyone that diligently uses VS-Code.

Before I go, I need to mention...

THE PITFALL

JSON didn't always lack support for comments. Comment support was removed from JSON after its initial definition was standardized. The reason for removing them comes from Douglas Crockford — the man credited for JSON's success — who is was quoted as saying, is the reason of removing comments from JSON as stated by

I removed comments from JSON because I saw people were using them to hold parsing directives, a practice which would have destroyed interoperability.

In other words, people were instructing the parser that was to parse their JSON. That made it so the files holding directives, would not be operable in another system that uses a different platform.

The above is a really good point, and it should be noted that Comments pose a similar issue. If you support comments in JSON, and try to use that JSON file in another environment, like a different editor, you have to make sure that editor also supports comments. This is simple for you because you remember whats in your files, or a good part of it anyways. However, when you pass a JSON file to a person who tries parsing it without opening it, they can get errors and won't know why. Because of these we need to be careful about the JSON files that we add comment support in.