Re: [AD] Renamed API third draft

[Grzegorz Adam Hankiewicz <gradha@xxxxxxxxxx>]

On Mon, Jan 07, 2002 at 08:45:11AM +0100, Hein Zelle wrote:
> I may have missed a vital reason here, but why not just
> 
> al_circle
> al_floodfill
> 
> ? I would think that adding a prefix (and the typing involved) is bad
> enough, I personally don't like adding an extra prefix for categories
> of functions. In my opinion, al_draw_circle and al_draw_line are just
> as clear as al_circle and al_line. Converting these functions to
> al_do_* definitely doesn't make sense, as it doesn't add any clarity
> _and_ makes the function name longer than the original.

Hold your breath. While I agree that typying_very_long_function_names
is tiresome, the new proposal strives for clarity, homogeneity, and
namespace friendliness. The al_ prefix is obligatory to fulfill the
latter. And to reach clarity and homogeneity, all function names should
have the most similar structure, which is al_verb[_noun(s)], or al_noun.

The problem with your proposal is that somebody may confuse al_circle
with a structure or variable name. I have been taught that using verbs
in function names can suggest the reader only functions, things that do
something, and the reason to have the verb before the noun is just to make
function names close to human language sentences (english, at least :)

Also, you might have not noticed that Allegro has at the moment: circle,
do_circle, line, do_line, etc. Which function does what?  It's clear that
do_circle means something about doing a circle. Doesn't it sound logical
then to have draw_dircle instead of circle alone?

The only problem I have is with al_floodfill (maybe some other functions
too I can't remember now). No matter how I think of it I can't gess
a correct naming, especially because floodfill doesn't exist on my
dictionary, but does sound to me like a real verb, maybe because I've
been using it for years. So I thought of proposing al_fill_flood,
al_fill_flooded, al_inundate_area, or something silly like that.

Since I can't "feel" the correct term because I don't know much about
natural english, and it's a function name which is pretty alone without
being grouped anywhere, I decided to leave that as it was, hoping for
somebody to get the right term. So far, nobody has proposed anything.

Heh, maybe it belongs to it's own addon package ;-)

> I'll re-read the discussion about the naming scheme, but this is one
> point where I don't like the new suggested API.

Well, I think that having the al_ namespace gives one nice advantage,
you can write your own wrapping api without namespace collisions, which
clearly is not possible now *thanks* to function names like line, or
circle, which are short and common :)

In fact, I was thinking of proposing later two different api headers
providing two different naming conventions: hungarian notation and
lua/libc notation (Allegro's underscore-less version), both with a
prefixed and unprefixed version. Prefixed version follows.

Hungarian: AL_DrawCircle, AL_DoCircle, AL_PutText, AL_InstallMouse, etc.
Lua/Libc:  al_drawcircle, al_docircle, al_puttext, al_installmouse, etc.

Since it's quite difficult to find al_whatever names in normal life,
it wouldn't be a problem for such a header to be a bunch of simple
#defines.  I didn't want to make this very official yet because I still
feel undecided to choose one api notation and adopt it for the rest of
my life, at least for personal purposes. The trouble is certainly that
I have used all of them and each has it's pros and cons (but yes, that
hungarian notation IS evil anyway :)

-- 
 Grzegorz Adam Hankiewicz   gradha@xxxxxxxxxx   http://gradha.infierno.org/