Tutorials

 By Shamus Aug 8, 2006 6 comments

A coding rant follows. It’s not for everyone. Or anyone. I’m just venting.

Last week:

I need a library to compress zip files. (By library I mean a .lib or .dll, I didn’t need a PROGRAM to zip files. I’m writing the program, and zipping files is a very small but very crucial aspect of what this program needs to do.) I need it quick. Money no object. (I’m not the one paying for it.) A quick Google search reveals that there are many, many out there. What hampers my search the most is that nearly all of them are documented by absolute stooges. To wit: When you write an example program demonstrating how to do such-and-such, you make that example as clean, uncluttered, as simple, and as short as possible. You do not make a production-grade program with dialog boxes and some convoluted MFC interface, a splash screen, an about box, or anything else that is not directly related to the task at hand.

I see this all the time and I can’t imagine what sort of imbecile would go to so much trouble to make something so useless. Several of the “example” programs I reviewed were many pages of C++ code, usually spread out over several modules and employing various elaborate class interfaces, and somewhere in what soup were the half-dozen lines of code that interested me and would show me what I needed to know.

Incompetence

Imagine if you had a tutorial for how to hammer a nail:

  1. Lengthy description of how to obtain the blueprint for a house
  2. Directions for how to select and prepare the building site.
  3. Long list of the tools needed. Somewhere in this list is buried the information about the hammer and how to use it.
  4. List of building materials. Somewhere in this list is a description of nails and how to hold them.
  5. Assemby instructions. Somewhere in here you might find instructions on how to arrange the two pieces of wood you’ll be nailing together.
  6. Instructions for adding a roof.

All of this comes in a hundred-page bound volume titled, “How to Drive Nails”.

This is one of the reasons I never bothered to learn DirectX. There was never a lesson on how to hook up with DirectX, start rendering, make ONE polygon, and then close DirectX. No, the tutorials were bloated, messy, and so confusingly written that I couldn’t tell which parts were DirectX calls and which were parts of the tutorial. Layers and layers of obfuscation were built up around function calls with confusingly similar (and painfully LONG) names.

Hmmmm. Am I supposed to call:
DirectXRenderTimeToDrawASinglePolygonPrettyPlease ()

or:
WowICouldReallyUseADirectXPolygonRightNow ()

No, both of those just turn around and call:
DxPolygonReadySetGoRender ()

Which in turn calls…
DxGimmieATriangle ()

But that’s just a container for… Um. Geeze. Forget this. I’m about ten levels deep and suffering from a personal stack overflow. I forget what I was even looking for when I started tracing through this mess.

(On the other hand, if you want to do a little rendering with OpenGL, NeHe is stellar. It starts with simple concepts (how to hammer a nail) and adds things one tutorial at a time, until you have everything you need to build a house. The tutorials are simple, as short as possible, and many are even cross-platform.)

So what happened with the zip library? I found one with a simple tutorial. The entire program would fit on one side of a single piece of paper. They also had the fastest, smallest external library out of all that I reviewed. I am of the opinion that all of these advantages are related. (The coders knew what they were doing.) As a bonus, the library as was also the cheapest. Amazing.

6Six comments, I think. Maybe half a dozen.


  1. Samrobb says:

    Just curious. Is there a reason that zlib didn’t fit the bill for you?

  2. Shamus says:

    I needed to be able to make zips that could be downloaded and opened using the windows built-in zip. As I read it, zlib is just as good, but also different enough that it wasn’t compatible.

  3. sun says:

    i was unable to understand the artical

  4. folo4 says:

    then, why many commercial games use DirectX even though the tutorials are as convoluted as you mentioned?

  5. Veylon says:

    Because DirectX is built into Sindows, because graphics cards support it better than OpenGL, and because it’s focused on Windows; it natively supports more file formats. Also, back when it was introduced, it provided a layer that everyone could use instead of having to fight directly with GDI or the hardware.

    Also, further, many companies use their own proprietary libraries on top of DirectX to make their code simpler and more portable, which is why you see Halo and Lego Starwars out for multiple platforms.

Leave a Reply

Comments are moderated and may not be posted immediately. Required fields are marked *

*
*

Thanks for joining the discussion. Be nice, don't post angry, and enjoy yourself. This is supposed to be fun.

You can enclose spoilers in <strike> tags like so:
<strike>Darth Vader is Luke's father!</strike>

You can make things italics like this:
Can you imagine having Darth Vader as your <i>father</i>?

You can make things bold like this:
I'm <b>very</b> glad Darth Vader isn't my father.

You can make links like this:
I'm reading about <a href="http://en.wikipedia.org/wiki/Darth_Vader">Darth Vader</a> on Wikipedia!