Detailed logging information (NCBC-270)

[NCBC-183] Docs should use Execute* methods with best practice error handling and logging in all examples Created: 14/Dec/12  Updated: 02/Jun/14

Status: Open
Project: Couchbase .NET client library
Component/s: docs
Affects Version/s: 1.2.0
Fix Version/s: backlog-1.0

Type: Technical task Priority: Major
Reporter: Jeff Morris Assignee: Jeff Morris
Resolution: Unresolved Votes: 0
Labels: None
Remaining Estimate: 24h
Time Spent: Not Specified
Original Estimate: 24h
Environment: http://www.couchbase.com/docs/couchbase-sdk-net-1.2/crud.html


 Description   
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.

http://www.couchbase.com/docs/couchbase-sdk-net-1.2/brewerycrud.html

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.

http://www.couchbase.com/docs/couchbase-sdk-net-1.2/crud.html


 Comments   
Comment by Matt Ingenthron [ 17/May/13 ]
This is probably not something we want to do as written. We want the simple approach to be, well, simple. Future API will hopefully make this better.
Generated at Thu Jul 31 21:32:44 CDT 2014 using JIRA 5.2.4#845-sha1:c9f4cc41abe72fb236945343a1f485c2c844dac9.