TEAM-ADA Archives

Team Ada: Ada Programming Language Advocacy


Options: Use Classic View

Use Monospaced Font
Show Text Part by Default
Show All Mail Headers

Topic: [<< First] [< Prev] [Next >] [Last >>]

Print Reply
"David J.A. Koogler" <[log in to unmask]>
Tue, 18 Jul 2000 15:02:49 -0400
text/plain (55 lines)
Randy Brukardt wrote:

> > If you're intending to claim that Microsoft doesn't document
> > their API thoroughly, I think you'll find a lot of skepticism.
> You've apparently never tried to use their documentation to build
> something substantial. Our experience building Claw is that the SDK
> documentation is full of errors and (especially) omissions. You simply
> cannot build working code by reading that material: you still have to
> write and test code on every platform that you intend to support.

Having worked with Windows starting with version 1.06 to the present,
I have to second Randy's comments. The documentation is adequate if you
know exactly what you have to do and only need to know details such as
parameter ordering and values. The SDK presents a microscopic view of
Windows. It does not present the big picture of how Windows actually

The key to engineering is the ability to predict. Without an overview
-- a Principles of Operation -- it is impossible to predict behavior.
You must resort to empirical trial and error measurements, and then try
to construct your own model of behavior. This is tedious, time
consuming, and error prone. At the end of the day you may succeed in
getting the program to work, but you still may not know why it works or
even if it should work. All too often the program will fail later for
unknown and mysterious reasons, and you are back square one. Randy's
example of control option behavior illustrates the problem precisely

>> Mind you, I have 2 or 3 books open on the desk and 2 or
>> 3 windows open on my computer whenever I do something
>> I haven't done before in Windows -- they aren't the greatest
>> at organizing their documents, but it's all there if you can
>> figure out where to find it.
> And I bet that you have to use a voting algorithm to figure out how to
> proceed, as at least one of them will be wrong almost all of the time.

Without deep understand of behavior, you are forced into the
cut-and-paste mentality. I don't know how many times I have seen people
desperately looking for an Petzold example they can use as template for
their solution. In many cases people copy the code so blindly they do
not even know what all the calls do, just that it gives them the right

Would a formal standard correct the situation? Perhaps not. Posix just
codified current Unix practice and tended to include all variations in
the standard (i.e. both bcopy and memcpy). However an honest attempt to
describe Windows behavior would have wonderful affect: we might even
be able to write reliable Windows applications if really knew what we
were doing. Of course if Windows did not do what was documented, then
the vendor would have to fix it.... :-)

David Koogler
Boolean Solutions, Ltd.