Uploaded image for project: 'Couchbase .NET client library'
  1. Couchbase .NET client library
  2. NCBC-270 Detailed logging information
  3. NCBC-183

Docs should use Execute* methods with best practice error handling and logging in all examples



      While proper error handling may be application-specific (some apps may be fine treating any error as "not found", while others need to handle those as very distinct cases, for example), I think the documentation the docs provide, and especially the tutorials and examples that people are likely to copy from, should perform explicit and thorough error handling and logging. Docs should make it easy for people to do it the right way.

      The current .NET docs have an OK example in the ASP.NET tutorial, where at least the return value is checked and exceptions are rethrown. So that's a good start, although there's no evidence of testing result.Success (which could be false, even if result.Exception is null). There's no mention, too, of what happens higher up when the result code is returned, and no logging of errors that folks can cut and paste.


      One method uses this:
      return result.StatusCode.HasValue ? result.StatusCode.Value : 0;

      While the others just return result.StatusCode.Value with no test. Why is that? Where is that documented?

      Then this example uses the non-Execute versions which don't allow for proper error handling. That may be OK in a very basic tutorial, but there should be a very clear and explicit pointer anywhere these are used that goes to a "Error handling with the .NET client" page that details why you shouldn't use those in most production code, and that you'll have a very hard time writing correct code unless you use the Execute* methods, and that also provides succinct and complete example for cut-and-pastability of correct error handling.

      Even so, I'd prefer that the basic "hello world" tutorial use Execute* methods in the first place, so people who only skim the docs only see the correct way to do things.


      No reviews matched the request. Check your Options in the drop-down menu of this sections header.


        No work has yet been logged on this issue.


          • Assignee:
            jmorris Jeff Morris
            jmorris Jeff Morris
          • Votes:
            0 Vote for this issue
            1 Start watching this issue


            • Created:

              Time Tracking

              Original Estimate - 24h
              Remaining Estimate - 24h
              Time Spent - Not Specified
              Not Specified

                Gerrit Reviews

                There are no open Gerrit changes