[prog] APIs for dummies?

[Jenn Vesperman]

On Fri, 2003-09-19 at 03:17, Akkana Peck wrote:

> Yes, this is how it works in C and C++ too, though there's a standard
> mechanism for it: files with a .h extension (called "header files" or
> "include files") are files containing function "prototypes": in other
> words, the specifications on how to call each function and what
> arguments they take (and, ideally, also comments explaining a bit
> more about how to use the function and what it's for).
> 
> So in C, you might put all your circle prototypes in circle.h, and then
> if graphics.c needs to use the circle routines, it just adds the line
> #include "circle.h"

I will add one more thing:

DOCUMENT.

Thoroughly document the API/function library/include file/module/
thing-a-ma-jig.

You need to include:
* The purpose of the library as a whole. What the application it hooks
into is supposed to achieve, the 'mental image' of the way it does it,
and how the library hooks into that.
Don't go deeply into technical detail, what you're trying to convey is
the overarching concept. You might understand that it's - say - a
graphic library for visualising intersections of cylinders, but someone
else might need to be told it draws ovals, ellipses, rectangles and
circles.

* The purpose of each function. See above. :)

* What each parameter of each function is, both in technical detail and
in concept. (I know it's an int, but is it a radius? A diameter? the
number of circles I want? And is it an input parameter or a result?)

* What each function presents as a result. See above.

* What, if anything, each function presents as a by-product. Does it
display on-screen? Does it modify anything else?



Hm. Anyone have any other pet peeves in not-fully-documented APIs and
function libraries?




Jenn V.
-- 
    "Do you ever wonder if there's a whole section of geek culture 
        	you miss out on by being a geek?" - Dancer.
   My book 'Essential CVS': published by O'Reilly in June 2003.
jenn at anthill.echidna.id.au     http://anthill.echidna.id.au/~jenn/