[PHP-DOC] Aliases for functions, and some "Official Function Naming Rules" From: Ron Chmara (ron <email protected>)
Date: 09/12/00

I have a small pile (well, three or four) hyperwave doc updates, waiting
on a ruleset. Let's see if we could build a concensus, eh? I'm intentionally
not looking at CVS to see who wrote what, that's not the point. What I am
trying to do is create some sensible rules for consistant appearance in
the code, the documentation, etc., so we can move forward with a plan. If
I use one of your code pieces, it's not because I have a vendetta. :-)

eschmid+sic <email protected> wrote:
> On Mon, Sep 11, 2000 at 12:50:42PM -0700, Lars Torben Wilson wrote:
> > Daniel Beckham writes:
> > > Do the aliases for mysql really need to be documented? It would seem that
> > > it would be much better to just add a <note> at the bottom of the proper
> > > <refentry> instead of actually creating an entry for it. I would think that
> > > we don't want people using the aliases and they are only there for backwards
> > > compatibility.
> > > BTW, many of the functions do have a <note> about their aliases already.
> > > Daniel
> > Well...I don't agree with 'much better'. 'Somewhat less cluttered in
> > the TOC', certainly. :) I do agree, now that you mention it, that
> > mysql_dbname() doesn't need to be there. However, despite the fact
> > that mysql_db_name() is an alias for mysql_result(), AFAIK it is
> > supplied as a sort of convenience function for folks who want an
> > easy-to-remember way to get db names; i.e. the semantics parallel
> > those of mysql_tablename().
> > Hm. That should probably be mysql_table_name(), come to think of
> > it. :)
> > mysql() I could go either way on.
> I agree with Daniel, only functions in function entries should be
> documented.

Rules:
RULE 1. Only major functions should be documented, functions which are
typographic variants may be mentioned, but should not be documented
as separate functions. They instead should be referenced in the
parent function as an alias. Functions which have completely different
names, however, should be documented as separate entries, for ease
of reference.

Examples:
mysql_db_name and mysql_dbname will be documented as the same function,
with the latter being listed as an alias of the former.

show_source and highlight_file will be documented as two different
functions (one as an alias), as the names are completely different,
and one name is not likely to be found if looking for the name of
the other.

> The nameing scheme for the MySQL functions are the best. It
> was a long discussion with Zeev that now every word in the function name
> is separated by an underline. This scheme had been adopted by many (not
> all) extensions.

RULE 2. Function names should be in all lowercase, with each word
separated by an underscore. Care should be used to minimize the word
count, and should include a parent name if they are part of a parent
set.

Good:
'mcrypt_enc_self_test'
'mysql_list_fields'

Ok:
'mcrypt_module_get_algo_supported_key_sizes'
(could be 'mcrypt_mod_get_algo_sup_key_sizes'?)
'get_html_translation_table'
(could be 'html_get_trans_table'?)

Bad:
'hw_GetObjectByQueryCollObj'
'pg_setclientencoding'

> Another nameing scheme had been used with PosgreSQL functions. Here all
> separate names are written without separator. The first character of
> single words have a capitalized letter. But function names are case
> insensitive, and so its no good idea.

Hyperwave suffers the same problem. :-) Since case is no longer an
issue, we can change it in the docs, and the code base will *gradually*
change to match... it may take a few years (or more), but if the change
is gradual enough, as old code is slowly retired, we can retain the
old names with no complaint, warn after a while, and maybe, someday,
5-10 years from now, it wouldn't break anything if the old functions
vanished. Maybe. :-) Perl is now having a "wiggle" problem, where
backwards compatibility with *Perl2* means sacrificing new
functionality possibilities....

A bad trap to get into, if it's _not_ planned for. If we plan now,
we'll know what to do later (or at least have a plan to revise).

RULE 3. Functions which are kept only for backwards compatibility should be
listed under their current parent names, and not documented as
separate functions. Backwards compatible functions and documentation
for them should be maintained as long as the code can be reasonably
kept as part of the PHP codebase.

> I hope that the PHP API will contain some rules for the code contributors
> how meaningful function names can be composed.
> IMHO there should be a warning message if someone uses an alias.

I think this could be the case if they are using a deprecated alias,
a few official releases after deprecation. This makes updates less painful,
and more gradual. It also keeps in line with the "two releases" on
the bugs... if we also add E_NOTICE before E_WARNING, astute developers will
pick up on it. That will take care of part of the code base, and legacy
coding. It also means that we aren't wasting valuable development time
on *naming scheme changes*, as the function names can be gradually
changed as code upgrades warrant it.

Example:
4.0.2 'pg_setclientencoding' <-long name, "retired in next release", 2000
4.0.3 'pg_set_client_enc' and 'pg_setclientencoding'<-(depr, notice) 2000(?)
4.0.4 'pg_set_client_enc' and 'pg_setclientencoding'<-(depr, notice) 2001(?)
4.1.0 'pg_set_client_enc' and 'pg_setclientencoding'<-(depr, warn) 2002(?)
...
4.2.0 'pg_set_client_enc' and 'pg_setclientencoding'<-(depr, warn) 2004(?)
...
16.0.7 'pg_set_client_enc' and 'pg_setclientencoding'(depr, warn) 2120(?)
...
146.0.0 'pg_set_client_enc' and 'pg_setclientencoding'(depr, error) 3000(?)
(The Y3K release ;-) )

The rules don't need to be set in stone, as long as there are guidelines,
they should gradually sort themselves out, and we can focus on maitaining
the active documentation, the active code, and put this naming/alias/case
issue to rest.

Okay, time to play skeet. I've thrown it up, now shoot down down the
bad ideas! Are any of the naming rules not good enough to add into
cvs:/php4/CODING_STANDARDS (which might need some other updating as well?),
and are the documentation rules good enough to add to cvs:/phpdoc/README?

-Bop 

--
Brought to you from iBop the iMac, a MacOS, Win95, Win98, LinuxPPC machine,
which is currently in MacOS land.  Your bopping may vary.