On 4/15/2011 3:55, Invisible wrote:
> In short, almost nothing is documented. I find this extremely frustrating.

It is all documented. It's just not documented in a place that it's easy for 
non-programmers to get to. Do you have an MSDN subscription, for example?

Basically, documentation of this type costs extra. :-)

> When you *buy* an expensive commercial product, you expect better than this.
> Sometimes you get it, sometimes you don't.

Yes, that's really my gripe. I'd be happy to pay $100 for a program I can 
get free elsewhere if it comes with good documentation. I'm still pissed 
that I bought a $300 modeler and they sent me the documentation from the 
version two generations back because they hadn't sold as many copies of the 
software as they expected and printed too many manuals 3 years ago.

The other problem is people are starting to write test-driven-design style 
documentation for products that have APIs. And that's just the *wrong* way 
to do things. You can't design a public API based on tests. Otherwise you 
wind up with crap like this:

this.Exit() will cause the game that's running ("this") to exit the next 
time it leaves the Update phase of the game loop. Unfortunately, you can't 
run two games in a row with the same process (say, for unit testing) because 
it also makes any subsequent games leave the update loop after the first 
time. Perfectly reasonable, as long as you never *tested* running two games 
in the same process and hence didn't design it to handle that.

There's like a dozen of these in XNA. There's an example of how to do 
things, and if you do things *differently* from the example, it screws you. 
Creating a new graphics device disposes of the old graphics device some time 
later in the initialization loop. You basically have
constructor->initialize()->update()->draw()->update()->draw()->...
If you reconfigure the graphics device in the constructor, the framework has 
apparently been holding onto the old one and disposes it for you. But if you 
load a texture in the constructor (instead of initialize), it uses the old 
graphics device (and stores it in the texture structure) even if you've 
already set up the new one. So when you later try to draw with the texture, 
it crashes out.  There are so many undocumented rules, you might as well 
just be as absolutely conservative as possible, because there's no 
documentation saying what you can't do, just examples of what you can.

Documentation by hypothesis and induction. The whole coding exercise turns 
into one giant cargo cult exercise. "I have to put this here and that there, 
because that's what the people before me did. I don't know why, but if I 
don't do what they did, the cargo won't come."

So there's an example of taking one model and drawing thousands of copies. I 
copy it and try to draw several different models using the same technique. 
OK, it works when I get my own bugs out. Then I add a model with two 
different textures, and even the ones that worked stop working now, except 
only on the xbox and not on the PC, so it's probably not my code at all. Now 
it only draws the first instance of each texture. But the example uses all 
kinds of routines that are documented with things like "Texture GetTexture() 
returns the texture."  Gee, thanks for that. Maybe the guy who writes the 
example in the documentation shouldn't be the guy who has access to the 
source code that actually describes what the crap does inside the library. 
Because there's no documentation about how to set any of that up or what it 
does beyond tracking through the type signatures of routines. And if you 
want to make a change, like use the *same* code to draw a *different* model, 
there's zero guidance, because your only documentation is how to do it with 
exactly the model that came with the sample code.

</rant>

I feel *much* bettahhhh...

-- 
Darren New, San Diego CA, USA (PST)
   "Coding without comments is like
    driving without turn signals."

Post a reply to this message