I’m starting the parser that will handle one of the key features of my app and realizing exactly who easy it would be for me to screw up a resource file that is provided to the application. For example, a simple resource that I provide to my app is a JSON file that contains an entity layout (name, fascia, location etc…). It would be easy for me to leave out the name of the entity or misspell the JSON key.
Obviously catastrophic failures during parsing are to be handled in a try/catch, but how would subtle failures (such as a dyslexic spelling of name) be handled?
What’s the difference between a “catastrophic failure during parsing” and a “dyslexic fail” (say a , instead of a ;, or a ' instead of a " – those two pairs of symbols are on neighboring keys on my keyboard), fundamentally, from the end-user’s* point of view?
If the JSON** is malformed due to a typo, giving a good error message is usually not trivial because from the parser‘s point of view, the (catastrophic) error might not be where the actual error is from a human point of view. So, in my opinion, the case you’re “dismissing” as a technical detail is the hard one to deal with.
If you have a valid JSON file, but missing (or extraneous) properties, giving a good error message (i.e. failing the right way) is comparatively trivial: just tell the user what you’re expecting that’s not there, or doesn’t have the right kind of value. You can make that even easier to the user if you state in the error message things like “keys are case-sensitive” or “dates must be entered in dd/mm/yyyy format” or whatever is relevant.
How you technically implement that will depend on the language, but keeping a list of mandatory and optional parameters (with their value types and default values) is not technically challenging – you could, in fact, do that with a JSON file that would be used both as input to your parser and as a source for your docs.
Build and maintain that list, and you’re done. Have a few testcase resources and make sure your parser (and “constructors”) fails hard (at least during automated tests) when a mandatory property is missing, or yields a big warning if an unknown property is present (not in that list).
If you add mandatory properties to your code, but forget to update that list, your testcases will tell you – either by the parser detecting that, or the “constructors” yelling at you because they’re missing data. Same thing if you change names or value types.
*You phrased your question in such a way that you seem to be the end-user. But if that resource loading is a key feature of your app, keep in mind that there will hopefully be many more people playing with that.
**Substitue any format here.
How would subtle failures (such as a dyslexic spelling of name) be
handled?
Unit testing. I don’t know what language you are using, but JUnit works great in Java and Scala. You are writing something that takes in some kind of input and produces JSON? Start by making a test that feeds it a known good input file and checks to see that the output is exactly what you want. Once you have a few tests written, you can change your code and have run the test to have a sense that the basic functionality that was there before is still working.
Another possible solution is to make your application that reads the JSON really good at reporting errors, deciding when to reject input vs. continue processing after an error is encountered (fatal and non-fatal errors), and correcting for small common mistakes.