*sigh*

Why is it so much coding resembles more the shaking of a voodoo stick (that is, the random trial and error by someone who appears not to have a freakin’ clue as to what’s going on) than it does the studied fix of someone who sees a problem, studies it to find out what is going on, then fixes the problem?

Perhaps it has something to do with the fact that most developers don’t know what they’re doing, especially when it comes to someone else’s code.

Many years ago I obtained a copy of “Inside Macintosh”, the document which outlines the Macintosh development API. Except back then, it was called a “toolbox”–the term “API” hadn’t been invented yet. (Yes, I’m dating myself.) One of the most remarkable things about the original documentation–something which most modern documentation fails to emulate (and which, in my opinion is a major contributor to ‘voodoo stick shaking’)–is the design and layout of each chapter.

Each chapter of Inside Macintosh documented one “manager”, a conseptual unit of code. For example, there would be a separate chapter for the “font manager”, another for the “event manager” and so forth. While the details of the specific managers nowadays would be different–we’ve learned so much since this document was published in June of 1983–it is the idea that we can decompose a program into conseptual units and what those units are: single conseptual units we initialize, manipulate, interact with, and shut down, which is the important part.

But what was most remarkable was how each chapter was organized.

The first part of the chapter was an “About”: “About the Event Manager”, “About the Font Manager”. This would be a two to 20 page summary of why the manager was there–what it did, and why, from a high-level point of view. The chapter on QuickDraw (the Macintosh Carbon API for drawing information on the screen) was quite extensive as it gave a detailed outline of how drawing occured, and what you could draw. This summary would then be followed by a number of sections outlining some of the key concepts, such as a section on event masks or a section on font kerning.

The second part of the chapter consisted of a “Using” chapter: “Using the Event Manager”, “Using the Font Manager”, “Using Quickdraw”, which itself would be organized into “Initializing”, “Using” (with appropriate sections) and “Terminating”. Some chapters would simply describe how to do something, some would contain sample code. But in all cases they indicated the name of the function that would need to be called. So, for example, from the “Event Manager” chapter:

Before using the Event Manager, you should call the Window Manager procedure InitWindows: arts of the Event Manager rely upon the Window Manager’s data structures and will not work properly unless those structures have been properly initialized. It’s also usually a good idea to call FlushEvents(everyEvent,0), to empty the event queue of any stray events left over from before your program was started up (such as keystrokes typed to the Finder.)

As noted earlier, most application prorams are event-driven. Such programs typically have a main loop that repeatedly calls GetNextEvent to retrieve the next available event, then use a CASE statement to decide what type of event it is and take whatever action is appropriate.

And so forth.

Aside from the sheer primitivism of the actual API being discussed, what is most striking is that the discussion tells you what API functions to use and why. This clearness means that you don’t have to shake the voodoo stick: you know that in your startup code you need to call FlushEvents–and more importantly, why you should.

The third section of each chapter would then consist of the usual listing of APIs that we see in things like JavaDoc output: a list of functions grouped by the type of stuff they do–so, for example, posting and removing events are grouped together and reading the mouse routines are grouped together.

Granted, today APIs have gotten expoentially more complex: after all, its far easier to shovel code than it is to think about and write good software. But even so, there is no reason why today’s APIs couldn’t be documented using the same formula: (1) What is it? (2) How do I use it? (3) The details.

All too often documentation (especially internal documentation) fails to provide the (1) and the (2)–ephemeral properties that only live inside the mind of the developer who figured out how to do it, and often never communicated to the guy stuck using it or debugging it, and instead go for (3)–and worse, go for (3) in the context of something like JavaDoc, which is a very nicely organized list of routines with no frakking explanation as to why I should care.

And so, lost in a maze of very poor documentation–documentation which could be quite good if only we’d add a page on what it is, and five pages on how to use it–programmers today have no choice than to either reconstruct the “what” and “how” themselves through wasting countless hours digging through the code, or (if the time pressure is on) shaking the voodoo stick, slaughtering a pig, and praying to the Gods of Code that what they stuck in causes the bug to go away.