Why does the documentation not include the Exceptions that may be thrown??

[bdcoder2]

The NetwtonSoft documentation seems to lack a LOT of detail. For example:

The documentation for JsonConvert.DeserializeObject Method (String) (which I picked at random), found at:
https://www.newtonsoft.com/json/help/html/M_Newtonsoft_Json_JsonConvert_DeserializeObject__1.htm

The documentation makes NO mention of the exceptions that may be thrown by this method, if any. However, if an invalid JSON string is passed to this method, the following exception is thrown:

Newtonsoft.Json.JsonReaderException

So, in reality this method should be wrapped in a try/catch when used.

I'll apologize in advance if I missed some preamble in the documentation that indicated all methods can throw an exception, but I find more and more "documentation" these days contains less and less details and I find myself wrapping all third party code in try/catch -- just because the documentation makes no mention of what exceptions (if any) may be raised.

[JamesNK]

Because it is low priority.

PRs to add exceptions to the documentation are welcome.

[bdcoder2]

How disappointing (but not surprising) in this day and age that great software lacks the most important thing -- great documentation.

ps: Because I don't have a document of acronyms, I have no idea what a "PR" is 😁

[cyberphone]

@bdcoder2 "PR" means Pull Request which is a Git way of introducing potential updates.

Regarding thrown exceptions, I prefer catching all exceptions in a few well selected places but I guess it depends on what kind of application you are working with...

[bdcoder2]

cyberphone, Just curious, how do you know where to catch exceptions if the documentation for whatever third party code you are using does NOT tell you if an exception can be thrown?

[cyberphone]

Hi @bdcoder2. I may be lazy but I just don't do any assumptions because third party code usually depends on OS/Platform features which in turn may cast exceptions as well. If there is a specific error condition you need to deal with in a unique way things become considerably more complex.

Where you catch exceptions is pretty application dependent, in my Web server stuff I surround the entire request code with a single try cast and return an HTTP 400 (Bad Request) + short message if something went wrong.

In Java there are "checked" (declared) exceptions but I find them mainly to be a problem for me as a designer of third party code.

[bdcoder2]

Agreed - I was simply trying t point out that the lack of documentation with regard to exceptions makes it IMPOSSIBLE to code efficiently. It has gotten to the point that I have to wrap third party calls in try/catch; even when it may not be necessary -- because I have NO documentation to tell me otherwise; but must code defensively.

The bottom line is, if you create libraries that are meant to be used by others, provide clear and detailed documentation. After 40 years of programming, I have witnessed the downfall of useful documentation.

[cyberphone]

As a true old-timer I agree that documentation has become less useful but it also has to do with the size, dependencies and fluidity of modern software. OTOH, Googling + Open Source + Stackoverflow + GitHub feels like a much more productive documentation system than was available for the Win32 API in the mid 90'ties.

Although clearly not my business, I don't fully get why you need to wrap calls to third-party software in try/catch. Personally, I have mostly given up that idea and rather treat all code the same. This is really the power of exception schemes over the previous (quite error-prone), C-style return code testing.

[bdcoder2]

"I don't fully get why you need to wrap calls to third-party software in try/catch." -- Because I have no idea if the third party code will cause my application to die and I want some control over flow and what happens.

Again, as we have both been around for such a long time, I am not so sure that having to Google + review open source code + asking questions on Stackoverflow is more efficient than being able to read documentation that clearly states "the following exceptions may be raised" or "No exceptions are raised".

Life was simpler back then :) - Cheers.

[cyberphone]

With heavy layered and complex software, traditional error handling feels pretty unworkable. Assume you have a readDocument command I would without hesitation do something like the following:

    try
    {
        doc = readDocument();  // Containing an arbitrary mix of own and third-party code 
    }
    catch (Exception ex)
    {
        // Messagebox/alert the user etc, gracefully exit/cancel/throw if needed
        // "Document couldn't be read because: xxxxxxxxxx"
        // where xxxxxxxxx comes from the exception's Message property
    }

If there is some very common error you can add a specific exception handler for that as well, However, using the scheme above this is just an option. Yep, a bit "raw" but the alternative, trying to figure all the error conditions worth dealing with separately comes at a price. I won't pay 😂

[bdcoder2]

Agreed -- that is what I am currently doing with all third-party software -- wrapping in try/catch -- but my original question is WHY SHOULD I HAVE TO? All I am asking is that developers take the extra 20 seconds to include a sentence or note that says (for whatever function they are "documenting":

readDocument() does NOT throw any exceptions.

I guess one could take the ultimate approach and have every program look like this -- simply devolve to a single try/catch statement and hope for the best :)

main()
{
   try
   {
      do_everything();
   }
   catch ( Exception ex)
   {
      // Messagebox/alert( "A program error occurred (no clue as to why) -- too bad for you.");
   }
}

[cyberphone]

Hi @bdcoder2! The ultimate approach is in fact what I'm proposing. The clue is taken from the Message property.

What you are asking for shows a downside of C#'s exception system versus Java's. In Java all application level exceptions MUST be declared. Too late to change and personally I don't worry about this, since the layered nature of modern SW, the frequent updates, and installable providers make "manual" exception handling a nightmare. I only use that for truly interactive purposes such as login functions.

BTW, if you read a corrupt JSON file, it seems hard coming up with a message to the user that they can actually do anything with. It probably worked better 20 years ago but then systems were maybe 100 times smaller with respect to code size.

Dealing with error-handling in multi-threaded applications is a way worse problem which I haven't found straightforward solutions to :-(