title: Return value: boolean vs int flag vs exception
body: <p>I need to define a set of functions as part of an interface for a public facing SDK and trying to figure out the best way of signalling to the caller code if something was successful or not, and if not, why not.</p>
  
  <p>My first consideration was return value vs exception. I think I need to use a combination of both for this one. Exceptions for erroneous states/errors caused by bugs. Return value to be used for times when function ran as expected and just want to return the result of the call to the caller.</p>
  
  <p>Now, for return type. I could use ints (flags) or booleans. It has been argued internally that booleans should be used as it is simpler, and no need for flags. Booleans limit you to specifying success or failure, with no explanation.</p>
  
  <p>I would make two arguments for using flags instead. First, you can return more than two possible values. Allowing for { success, fail, fail_reason_1, fail_reason_2, fail_reason_3 }. Note as this is an interface for implementations on various hardware devices it is probably desirable to be able to notify why an operation failed. e.g. the connected device doesn't support beep, has no LCD, doesn't support embedded crypto etc.</p>
  
  <p>Who knows what the requirements will be in the future. Returning a bool locks you in now, whereas using flags allows you greater flexibility in the future. So what if you never need more than two values in the future. At least you have the option.</p>
  
  <p>Considering this will be a public facing SDK I want as much flexibility so as to prevent breaking changes in the future.</p>
  
  <p>Thanks</p>