Commenting .json config files

Question

I've been digging into ASPNET 5 and MVC6. A major change from previous versions is that in the new version, many of the configuration files are .json rather than .xml.

Trouble is two-fold:

1. Configuration files often need comments for maintainability, and for debugging (E.G. Comment out original lines while modifying the config to make it easy to go back to the original if the changes don't work well.)
2. .json doesn't support comments, except through hacks. There are numerous hacks to add comment support into JSON, many are mentioned here. However, there isn't much of a standard as to which hack should used to keep code readable, maintainable, and (hopefully) compatible with the tooling of Visual Studio.

It would be a big step backwards in developer experience if each developer chose their own comment hack, or simply stopped adding readability comments into config files. Additionally, Visual Studio has comment/uncomment shortcuts that work in all languages that support comments that are used heavily by many developers during development and debugging cycles. The dev world doesn't need another "Don't forget that in this one situation that the regular stuff doesn't work and you need to do this other thing."

Is there any Microsoft (or similar) guidance on what method of hacking comments into the .json configuration files is "best" with Visual Studio and the MS tool chain?

Answer 1

The standard AddJsonFile configuration extension in dotnet core allows comments and trailing commas in the JSON: https://github.com/dotnet/runtime/blob/main/src/libraries/Microsoft.Extensions.Configuration.Json/src/JsonConfigurationFileParser.cs#L26-L27

And you can configure that in your own JSON parsing too: https://learn.microsoft.com/en-us/dotnet/standard/serialization/system-text-json-invalid-json?pivots=dotnet-core-3-1