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

Ron wrote:
>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....

Also, studlyCaps are just ugly :) IMHO

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

These ideas all make sense to me - especially formalizing the function
naming standard. I am happy to sacrifice a small amount of extra length
for enhanced readability. Those who are not satisfied with the length of
names can always use their own function name aliases.

i.e.
$alias = 'amazingly_long_function_name_probably_a_hyperwave_extention';
$alias ('foo');

0.02

  - Zak