No, JSON can't have comments. The standard has no comment syntax, so a // line or a /* ... */ block makes a strict parser such as JSON.parse throw an error. If you need notes in a file, you have to use a JSON dialect that allows them (JSONC or JSON5), strip the comments before parsing, or store the note as ordinary data.
What the spec says
The JSON standard is RFC 8259. It never mentions comments. Between tokens it allows "insignificant whitespace", and it lists exactly four characters that count: space, horizontal tab, line feed and carriage return. A slash isn't one of them, so a comment is neither whitespace nor a value. It's a syntax error.
I parsed this config in a recent Node.js release:
JSON.parse(`{
// port
"port": 8080
}`)
// Expected property name or '}' in JSON at position 4 (line 2 column 3)
The parser read {, skipped the newline and spaces, and then hit a / where it wanted a key in double quotes. It doesn't know that // is meant as a comment. Python's json.loads gives the same verdict with its own wording: Expecting property name enclosed in double quotes: line 2 column 3 (char 4). A block comment after a value fails the same way; {"a": 1 /* x */} gave me Expected ',' or '}' after property value.
Neither message says "comment", which is why this one trips people up. When a parser complains about a missing property name at the start of a line, look at that line for a //.
Why JSON has no comments
Douglas Crockford, who specified JSON, explained it in a 2012 post that was shared on Hacker News: he removed comments because he saw people using them to hold parsing directives. The nlohmann/json documentation quotes the rest of his reasoning. He called that practice one "which would have destroyed interoperability."
Picture one parser reading /* @strict */ as an instruction while another ignores it. The same file now means two things depending on who opens it. His suggestion for people who wanted comments, as paraphrased in the same thread, was to write them anyway and strip them out before handing the text to a parser.
The standard does leave a gap. RFC 8259 says "A JSON parser MAY accept non-JSON forms or extensions," so some libraries let you opt in. The C++ library nlohmann/json rejects comments by default, but with ignore_comments set to true it treats // and /* */ as whitespace.
Why some .json files accept comments
You've probably seen comments in tsconfig.json or VS Code's settings.json and assumed JSON allows them. Those files aren't strict JSON. VS Code opens settings.json, tasks.json and launch.json in a JSON with Comments (jsonc) mode, which allows // line comments and /* */ block comments. The mode accepts trailing commas too, though the editor warns about them. The tool that reads the file uses a matching parser, so the comments never reach a strict JSON.parse.
Trouble starts when some other tool reads the file. A build script that runs JSON.parse(fs.readFileSync('tsconfig.json', 'utf8')) crashes on the first comment. The file extension says .json; the content says JSONC.
If you want VS Code to stop flagging comments in your own config file, change the file's mode from the mode indicator in the status bar, or map the file name to jsonc in the files.associations setting. That fixes the editor, not the program that reads the file.
Your options when you need notes
1. Use a dialect that allows comments. JSON5 allows single-line and multi-line comments, along with a few other relaxations. JSONC is the lighter option: JSON plus comments (and tolerated trailing commas). Both are meant for files people edit by hand. JSON5 says plainly it isn't intended for machine-to-machine communication.
2. Strip comments before parsing. This is what Crockford suggested, and the strip-json-comments package does it:
import stripJsonComments from 'strip-json-comments';
const config = JSON.parse(stripJsonComments(text));
It swaps each comment for whitespace rather than deleting it, so error positions from a later mistake still line up with your original file. Trailing commas are left alone unless you turn on its trailingCommas option.
3. Put the note in the data. A key like "_comment": "port must match the proxy config" is valid JSON everywhere. The catch is that it is data. Every consumer sees it, a schema that forbids unknown fields will reject it, and you can't attach it to a specific line inside an array.
4. Keep the notes elsewhere. A README next to the file documents the format without touching the data at all.
My take: use JSONC for config files a human edits, and make sure every tool that reads them knows it's JSONC. Anything sent over the network or written by one program for another stays strict JSON, no comments. The _comment key is the worst of the four. It's valid, but it turns documentation into fields your code has to know to skip.
The dialect route has a cost. Once a file depends on comments, every linter, CI script and language that touches it needs a parser for that dialect, and a plain JSON.parse will always reject it.
Checking a file for stray comments
If a config file won't parse, paste it into the OnlineViewer JSON validator. It reports the JSON.parse error with its position, and the check runs in the page, so you can use it on files that hold credentials. A comment will show up as an "Expected property name" or "Expected ',' or '}'" error at the slash.
Two related errors look similar. A comma left before ] or } is covered in why JSON doesn't allow trailing commas, and an empty or cut-off body is explained in what "Unexpected end of JSON input" means.
FAQ
Does JSON support // comments?
No. The JSON standard, RFC 8259, has no comment syntax at all. A strict parser such as JSON.parse or Python's json.loads throws an error when it reaches // or /*.
Why were comments removed from JSON?
Douglas Crockford said he removed them because people were using comments to hold parsing directives, which he said would have destroyed interoperability between parsers.
Why do tsconfig.json and VS Code settings.json allow comments?
Those files are read by tools that use a JSON with Comments (jsonc) parser, not a strict JSON parser. They look like JSON but are a different dialect.
How do I add a comment to a JSON file anyway?
Either switch the file to a dialect that allows comments (JSONC or JSON5) and use a matching parser, strip the comments before calling JSON.parse, or put the note in an ordinary key such as "_comment" that your code ignores.