Quote: Original post by StarfoxQuote: Original post by Crazyfool
I like the MSDN as well, but for reasons I obviously don't understand, certain functions can return values that are not listed as possible return values. There was a thread I made about it. Granted, it was clearly an issue with my computer (and still is), but I think listing all the possible return values is best when listing possible return values. Simply put, they could say "can also return a value from X" in which case it may be a very long tree of possible returns, but at least I'd know the true possible return values.
That's impossible without a time machine. Think about it: HRESULT Foo() return the possible error code. It can be reliant on a, say, HRESULT from a third party COM component which might return new errors in the future, that's why there's a failt bit in HRESULTs, or docs say something like "On success, returns X, on failure returns Y, Z, W or other error codes" - because if you code your app on windows 7 assuming only Y, Z or W are possible error codes windows 8 will add a new error code and break your app. Happened in MSDOS btw, when networking was introduced. I think Larry Osterman's blog had more information about that last topic.
And that's a flaw in the API design. Return codes get hijacked all over the place to report error state, instead of performing the natural job of returning the result of a calculation.
Granted, it's a historically justified design flaw (no exceptions way back when), but it's gone to extremes in the name of "consistency". And worse, it trains programmers to think that way.
I once spent hours reviewing a colleague's Java code, statically proving that no error conditions were possible except for those that would throw an uncaught RuntimeException anyway, and stripping out huge reams of code used to propagate error codes down the stack (which exceptions do automatically). It wasn't even checking for the conditions that might cause an exception to be thrown, and even if I did, that would be far from optimizing for the common case.
Short code is elegant code.