Re: [AD] Renamed API third draft

[Hein Zelle <hein@xxxxxxxxxx>]

Grzegorz Adam Hankiewicz wrote:

> 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.

I agree with that general idea, and the fact that al_ is necessary
doesn't need to be discussed, it's clear.

> 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 :)

I see your point, although I think it's overdone. In a graphics
package, I have no trouble whatsoever understanding that

circle()
line()
rect()

etc are functions, and not variables or 'things'. Although I agree that 

    if (! al_draw_circle())
       al_draw_line();              // ignore rediculous example code

sounds very pretty when pronounced in english, I get the feeling that
when programming games it would get rather cumbersome having to write
draw_ before every function that draws something. Now if allegro did
something else with lines and circles, that would make a
difference. But even when they _would_ be variables, or structs,
they'd be written as LINE, CIRCLE. I see no way how anyone could
confuse the meaning of line() and circle(), apart from the fact that
any C programmer can _see_ that it's a function in the declaration.
       
> 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?

That had had indeed escaped my attention. I think it is not fair
reasoning though to adapt line() and circle() because do_line and
do_circle are not clear. I personally would call these something like
line_proc() or line_func() or even line_do(), but that would go
against your verb_noun convention (noun_verb).

Trying to come to some form of a conclusion, I think that I
principally disagree that every drawing function has to be of the form
verb_noun. In my opinion, it doesn't add clarity, just extra typing. I
would stick to your other convention where possible: al_noun().

For do_circle and do_line I don't have a ready solution with this
convention, but following al_verb_noun I would end up with al_do_line or
al_proc_line or something like that.

For floodfill I would stick with Martijn's suggestion: it's a common
verb in graphics packages so just leave it at al_floodfill(). I do not
wish to discuss your Hungarian notation in public :-) (except for one
remark: why use Al_Func and not just AlFunc?)

Hein Zelle

>-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-<
 Hein Zelle                     hein@xxxxxxxxxx
	                        http://www.icce.rug.nl/~hein
>-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-<