On Thu, 5 Dec 2002, Harrie Hazewinkel wrote:
> On Wednesday, December 4, 2002, at 02:49 PM, Derick Rethans wrote:
>
> > Hello,
> >
> > while browsing the CVS I found that the following functions were added
> > to the CVS recently:
> >
> > + PHP_FE(snmpv3get, NULL)
> > + PHP_FE(snmpv3walk, NULL)
> > + PHP_FE(snmpv3realwalk, NULL)
> > + PHP_FALIAS(snmpv3walkoid, snmpv3realwalk, NULL)
> > + PHP_FE(snmpv3set, NULL)
> >
> > But those functionnames don't adhere to our nameing guidelines.
>
> Naming guidelines?? Which I look the last time at some pointers
> given for this, but I could not find naming guidelines. It would help
> if you can point me to the precise part defining this.
I quote: (from php4/CODING_STANDARDS)
[1] Function names for user-level functions should be enclosed with in
the PHP_FUNCTION() macro. They should be in lowercase, with words
underscore delimited, with care taken to minimize the letter count.
Abbreviations should not be used when they greatly decrease the
readability of the function name itself.
Good:
'mcrypt_enc_self_test'
'mysql_list_fields'
...
[2] If they are part of a "parent set" of functions, that parent should
be included in the user function name, and should be clearly related
to the parent program or function family. This should be in the form
of parent_*.
A family of 'foo' functions, for example:
Good:
'foo_select_bar'
'foo_insert_baz'
'foo_delete_baz'
...
[5] Variable names should be in lowercase. Use underscores to separate
between words.
more of all, it's common practise with all extensions. If you find some
which do not adhere to this standard, then there was taken into account
a BC problem. This is not the case with new functions, like you added,
and thus they should stick to the guide lines.
>
> > As those
> > are new functions I propose to change them to the following, to be more
> > consistent with all other functions:
> >
> > snmpv3get -> snmp3_get
> > snmpv3walk -> snmp3_walk
> > snmpv3realwalk -> snmp3_real_walk (or snmp3_walk_oid)
> > snmpv3set -> snmp3_get
>
> I have mentioned this some time ago already on the list. (See archive)
> I believe it is way easier for people to recognise the SNMPv3
> version by people with the current naming. On top of that I can
> understand all of your concerns, but it is my opinion we have to think
> what is the easiest for the users/programmers of PHP.
the proposed names are much more readable, and they follow the oci8_
convention of only using the verison number, the 'v' in your names don't
add anything useful.
> IMHO, the current naming refers quite clearly to SNMP version 3
> or SNMPv3. Many people know this version of the protocol as SNMPv3.
> I beleive that the original functions did neither have an '_'
> character. Why is that required suddenly??
Backward compatibility for those. Maybe you noticed that we added some
aliases to other extensions because of this, but the snmp extension was
left alone in that. AFAIK, changing or aliasing names is on the PHP 5
todo.
> (This states more or less the same opinion as expressed last time)
>
> I also would like to mention that I am looking into the usage
> of an SNMP-session creation and then use a single variable to
> provide all SNMP-session info in a single variable for the
> 'data retrieval' functions. Therefore, I would like
> to reserve the use of the underscore and then without a version
> number.
As long as you don't break BC it's fine with me.
>
> > also, there is no need to introduce an alias for a newly created
> > function so I guess we just should drop it.
>
> I have created a similar set of functions as exist for SNMPv1.
> That includes the alias. That makes it easier for existing scripts
> to be updated with the new security featres of SNMPv3.
We only add aliases if it is absolutely necesary, which is really not
the case here.
> > I'd like to make those proposed changes ASAP as they are also added in
> > the PHP_4_3 branch which gets closer to release everyday.
>
> Personally, I do not prefer and like the name change suggested.
>
> The name snmp3_ looks to me quite weird, since the world
> knows this as SNMPv3. Therefore, the use of snmpv3 is preferred.
yeah, and oci is really called oraclecinterface, so let's fix that too!
> I am even tending to give it a -1, but there is not technical
> reason. But there is neither a good technical reason
> in favour of the name change.
It has little to do with a techincal reason, but more of a logical one.
As all functions in PHP extensions follow the same nameing style this
makes it easier for users to work with it; that's the main concern here,
and that's why I'd like to change the names.
Derick
--
-------------------------------------------------------------------------
Derick Rethans http://derickrethans.nl/
PHP Magazine - PHP Magazine for Professionals http://php-mag.net/
-------------------------------------------------------------------------
--
PHP Development Mailing List <http://www.php.net/>
To unsubscribe, visit: http://www.php.net/unsub.php
