httpd-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Rodent of Unusual Size <Ken.C...@Golux.Com>
Subject Re: cvs commit: apache-1.3/src/test/rename apapi.h apapi.h.mk rename.cf
Date Tue, 07 Apr 1998 11:23:21 GMT
Roy T. Fielding wrote:
> 
> >Please, let's drop this guff about "apapi_ is too long."  That's
> >a personal opinion, no more.  I've been having to deal with X API names
> >(extremely minimally, thank goodness!) and other library API names that
> >look like lib$convert_date_string and str$find_first_not_in_set - and I've
> >dealt with names like this for years.  It's not necessarily good, but
> >neither is it necessarily evil.  If name length adds to clarity, I'd
> >generally lean toward it begin good as a prejudice.  (Those are
> >pathological examples that I think would be candidates for shortening -
> >but it's not my API.)
> 
> They are all examples which demonstrate that long prefixes are a bad idea.

Erm, no.  You'll notice that none of those have long prefixes.
'X' and 'Xt' are hardly a strain; nor are 'str$' and 'lib$'.  My
point above has to do with total symbol length and how I consider
confusing it with the prefix to be a bogus argument.

> I see no reason to repeat the mistakes of other projects.  I worked in
> the VMS world for a little over a year, and it is my opinion that such
> things were (and are) a total failure.  Whether or not DEC used them is
> totally irrelevant to their goodness, particularly since DEC has never
> been good on the software side of things.

I certainly shan't argue that!  However, they *have* been very good
about defining - and sticking to - a rational nomenclature.  If you
encounter the symbol EXE$FOO, what is it and where do you find out
about it?  It's a kernel routine, so look where those are described.
What's MMG$GL_BAR?  It's a 32-bit global kernel cell having to do
with memory management.  BAS$EDIT?  A BASIC language support routine
in the BASIC library.  LIB$FIND_IMAGE_SYMBOL?  The OpenVMS equivalent
of dlopen()/dlsym(), found in the LIB library.  RMS$$ZED is a
routine internal (i.e., not documented nor for public use) to the
Record Management Services, whilst RMS$$AB_OMEGA is a 32-bit pointer
to an RMS-internal byte cell.  The symbol names are descriptive
in both the functional and implementation axes.

I've worked in the VMS world for almost twenty years, and it is
*my* opinion that the nomenclature works exactly as intended,
and well, and is not a failure at all.  I consider it a distinctly
better system than the arbitrary what-the-hell naming in the UNIX
world, where you can't be sure from system to system where a
routine lives or what its return datatype is.

I have to admire the care that went into designing the VMS nomenclature,
and the rigour that has gone into implementing it.  You can tell by
looking at a name whether it's a routine or a data cell, whether
it's part of an API, and where to find documentation about it.
It's just unclear whether anything resembling this rigour is
appropriate for the Apache software portfolio.

> Now that I have successfully tested Ralf's scripts (and brilliant work
> it is), I am even less inclined to believe in this prefixing names as
> a means for differentiating between purposes.  All of the symbols that
> look like ap_whatever are clear and to the point.  All of the symbols
> that look like apx_whatever are confusing -- confusing because there is
> no apparent reason for the difference, nor is there any need for the
> difference, nor is the difference "correct" in any sense because I am
> certain that some of those symbols are intended to be public, and finally
> confusing because "apx_" interferes with readability of the names
> significantly more that "ap_" (33% more, in fact).

I submit that almost all of the above is purely subjective.  On a
subjective level, I disagree as follows:

 o If there is no apparent reason for the difference between apx_ 
   and ap_, it *might* have something to do with a meaningless
   prefix having been chosen.  It *might* also seem that way because
   you're so familiar with the historical arrangement that you
   can't be unbiased in your judgment.  (Not a slam or criticism.)
 o If apx_ is being used for some symbols that are supposed to be
   public, that's a defect in the identification of those symbols
   as private and hardly the fault of the prefix.
 o I submit that "apx_ is 33% less readable than ap_" simply
   because 'x' is an arbitrary string conveying no additional
   information.

> I strongly recommend you actually run Ralf's script (on a separate copy
> of your repository) and then compare http_main.c.bak versus http_main.c.
> There is a world of difference between the individual prefix options.

A very valid point.  I've been arguing from principle, so let me
do this exact thing.

> This prefix argument has been on the table now for a long time.
> Unless four people suddenly change their minds, we are going with
> just "ap_" and nothing more.  I'll wait another 24 hours to be sure.

Yes, Master.  Do I seem restive in the face of a unilateral time-based
decision?  You bet - our official *release managers* don't have
this authority, so whence comes yours?  Sheer 'elder statesman'ness?
But perhaps I'm misreading your tone - easy to do in email.

If there is a significant division of opinion, arbitrary ultimata
seem inappropriate.

I'm going to go inspect the results of Ralf's scripts and shut up
until then.

#ken	P-)}

Ken Coar                    <http://Web.Golux.Com/coar/>
Apache Group member         <http://www.apache.org/>
"Apache Server for Dummies" <http://Web.Golux.Com/coar/ASFD/>

Mime
View raw message