Make some sort of mention in defaultPreferences.json somewhere that the actual brackets.json file does not support comments!

[Rannison]

I know many of you here might think it too obvious to even be worth mentioning, but please consider this perspective from a new student or layman...

You've just been told by your class instructor to download and start using Brackets IDE in your first programming class. You install it and fire it up, then go through all the configurations, download some extensions, and then eventually you reach the open preferences file menu option (which you of course have to proceed to monkey around with). Two side-by-side panes open up, and one claims to be an alleged "reference" source, from which you should "reference to modify your preferences file". So you do exactly that: you copy over a few lines that have unobfuscated vernacular you can actually comprehend (or at least you're pretty sure you think you do) and sound neat to have enabled.

And then you save the file.

A flash of light blinds and confuses you, and as you squint at your screen in confusion and disorientation, you realize your actions have caused your dark-theme to go AWOL on you. And so you carefully check each line with a fine comb, all the while squinting at the wall of white flashbanging your eyes. Everything looks correct as far as you can tell. You see one difference is the line spacing between each line, so you try adding a line return after each line. You double check that all your indentations match up correctly to the reference source. You even try commenting out several of the preferences that aren't shown in the support resource page's table of supported preferences. Nothing works. Finally, in true PC diagnostics fashion, you comment out every single preference, all save for one — your dark theme — and you offer up a prayer as you hit save...which promptly finishes as an expletive instead. You look back to your other monitor and you realize your instructor's asynchronous lecture already finished quite some time ago, yet here you are not able to even finish setting up the damn thing so you can get started.

Several hours later, your future career as a code monkey is off to a promising start, and you aren't at all fazed that you left your $70,000-per-year job in order to pursue your passion for computer programming and crippling debt. Then finally, after exhausting all the relevant resource pages and burning that white wall into your retinas, you resign yourself to having to be that one noob that has to post an issue because they couldn't figure out how to configure their installation without bricking it. Thankfully, you take the time to at least glance through some of the threads, and by pure dumb chance you happen upon one that makes mention that the .json file does NOT support commenting 😱😱😱. In a fit of rage, you go back and scour defaultPreferences.json — even though you've pretty much committed the entire thing to memory at this point. Nowhere, Nowhere, does it state, "hey, go ahead and copy me over to the other pane, but just make sure not to copy any of the lines inbetween that are comments, mkay?". "How could you?", you wonder, feeling betrayed. "I trusted you like the Holy Bible!".

Okay, so in all seriousness though, most of that was pretty faithful to my first meeting with Brackets (minus the dramatic narrative). I think it would save more than a few headaches to prospective new users if this were to be made more obvious, and the best instructions are always the literal ones...you know, the ones that are written like they were meant for a neanderthal that wandered into the 21st century and has the same intellectual prowress as a five year old.

[charlypa]

@Rannison Thanks for the feedback.
We are revamping the configuration experience

meantime you may download revamped brackets
We've updated our editor to Phoenix Code, launched just yesterday. It now supports Windows, Mac, and Linux moving beyond the older Brackets x86 binaries.
You can download Phoenix Code at https://phcode.io/.