Advertisement

MSDN: Pretty good, or pretty bad documentation?

Started by September 28, 2009 02:08 PM
24 comments, last by Washu 15 years, 1 month ago
Quote: Original post by Starfox
Quote: 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.
Quote: Original post by Zahlman
Quote: Original post by Sneftel
Universities are Unix shops. Some bias is to be expected.


This. To be fair, it's pretty justified on their part: they don't have the time or resources to teach you to use an IDE at the same time as a programming language (actually, does anyone even really know how to teach use of an IDE?), and Unix does tend to make it easier to do things at the bear-skins-and-stone-knives level. Just as long as you get to use a text editor with mouse support. :)

"Bear-skins-and-stone-knives" is right. I just got through using ddd to step through and analyze an executable, without access to source code. Of the three hours spent, more than half was trying to do things (like view the memory a register pointed to) that should be done by a simple mouseover.

Going back to Visual Studio just makes me so, so happy.
Advertisement
Quote: Original post by BeanDog
Quote: Original post by Zahlman
Quote: Original post by Sneftel
Universities are Unix shops. Some bias is to be expected.


This. To be fair, it's pretty justified on their part: they don't have the time or resources to teach you to use an IDE at the same time as a programming language (actually, does anyone even really know how to teach use of an IDE?), and Unix does tend to make it easier to do things at the bear-skins-and-stone-knives level. Just as long as you get to use a text editor with mouse support. :)

"Bear-skins-and-stone-knives" is right. I just got through using ddd to step through and analyze an executable, without access to source code. Of the three hours spent, more than half was trying to do things (like view the memory a register pointed to) that should be done by a simple mouseover.

Going back to Visual Studio just makes me so, so happy.


Being in Visual Studio kind of implies having the source, yeah? So the comparison hardly seems fair.
No, you can debug a process without source with Visual Studio. It's a pain and a half, but still not as bad as some other debuggers.
Quote: Original post by Zahlman
Quote: Original post by BeanDog
Quote: Original post by Zahlman
Quote: Original post by Sneftel
Universities are Unix shops. Some bias is to be expected.


This. To be fair, it's pretty justified on their part: they don't have the time or resources to teach you to use an IDE at the same time as a programming language (actually, does anyone even really know how to teach use of an IDE?), and Unix does tend to make it easier to do things at the bear-skins-and-stone-knives level. Just as long as you get to use a text editor with mouse support. :)

"Bear-skins-and-stone-knives" is right. I just got through using ddd to step through and analyze an executable, without access to source code. Of the three hours spent, more than half was trying to do things (like view the memory a register pointed to) that should be done by a simple mouseover.

Going back to Visual Studio just makes me so, so happy.


Being in Visual Studio kind of implies having the source, yeah? So the comparison hardly seems fair.

Not true, actually. It's pretty trivial to attach the VS debugger to any binary you'd like to run (or are already running). I just used it to stop a Chrome process and have a look at the disassembly. Sure enough, it's extremely trivial to do the kinds of things that I wasted my morning on today.

Edit:Beaten to the punch.
Quote: Original post by Zahlman
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.

Yes and no. HRESULTs are platform independent in ways that exceptions are not. A C# exception is not trivially caught in C/C++, and a Java exception is not trivially catchable in C#. In fact, exceptions in general tend to be highly specific to a language, platform, or compiler. Exceptions, in the big outdoors world of actual software development, are nice for small bits and pieces of code that you can guarantee will only operate within a small domain of influences (say a piece of software written entirely in C#). Once you start to move outside of that you introduce interoperability issues that have not, nor will ever, be dealt with in some manner that makes exceptions magically platform independent. Hell, even throwing an exception through SOAP ends up differing in the details from platform to platform, while still conforming to the standard.
Quote: 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.

Yes, and this is a case for exceptions. But when you deal with COM, or other componentized models exceptions quickly start to cease to be an elegant method of dealing with errors, and tend to devolve into a mess of wrapper code to catch/check and handle errors in a manner the rest of the language can handle nicely. I'll keep my COM HRESULTs, kthx.
Quote: Short code is elegant code.

Not always true. I've seen plenty of short code that was anything but elegant.

In time the project grows, the ignorance of its devs it shows, with many a convoluted function, it plunges into deep compunction, the price of failure is high, Washu's mirth is nigh.

This topic is closed to new replies.

Advertisement