Re: Function renaming. First attempt at defining some rules.

At 14:54 14.2. 2001, Phil Driscoll wrote the following: -------------------------------------------------------------- >I've been discussing the business of function renaming etc with my colleague >Tony, who has far more experience in designing elegant languages and >instruction sets than I have. >The following is a distillation of our combined thoughts. > >Firstly, I'm not sure that the way we are discussing things at the moment is >quite getting to the root of the problem. Most posts are using a favourite >group of functions, or the popular rule breakers as an illustration of how >things should be changed. I think we need to get to the nitty gritty and >write down what the rule should be. On the other hand, I think that the rules cannot be defined without trying them in practice -- they will definitely be subject to constant revision. If we don't define the rules on our way through the process, we might get into situation where we find out that the rules cannot be applied for whatever reason. That's why I started submitting renaming proposals. >There seems to be general agreement that a function name should begin with >the name of the extension which provides it (eg mysql). There also seems to >be agreement that the extension name should be followed by an underscore. >Several functions are deemed to be 'core' functions and should be allowed to >have no prefix (possibly in addition to an alias which does have an >extension prefix). I think we have agreed on this. >All the functions do something, so without fail a verb is involved to tell >us what the function does. In the simplest cases, no more is needed as >extension_verb tells us enough (e.g. mysql_connect), but for more complex >functions, the verb needs a noun to tell us which object the verb is doing >its stuff to (e.g mysql_list_tables) (note that some extensions only act >upon one type of object, so there may be a case for omitting the object when >it is implicit?), and often it is some property of the noun we actually wish >to affect (e.g. mcal_set_event_title - yes, I know this isn't how it >currently is!). Finally (hopefully!) we sometimes wish to add an adverb to >tell the verb how to behave - e.g. be case sensitive, raw, etc. In some >existing cases, this adverb is rolled into the function name, but in others >(and a better and more versatile solution, we think) the adverb is an >optional final bitfield, boolean or integer argument to the function (as in >sort(array array [,int sort_flags])). IMO requiring a verb in all function names is too much. While rigid purity might be a goal, I'm not after it. The world isn't black and white. Requiring e. g. "get" might be feasible if the function has a "set" counterpart. But <db extension>_error is a good function name IMO. I prefer it over <dbext>_error or <dbext>_get_error or <dbext>_get_error_message or <dbext>_geterrormessage. >So, what this gives us is: > >extension_verb[object][property](...,[adverb]) So you mean you're in favor of nuking all those arsort's, krsort's and alike and replace them with flags to [array_]sort? I don't like that idea. >Then we have to look at consistent use of verbs. One point which came to >light was to standardise on set and get, rather than the rather erratic use >of set, get, fetch, read, write. > >When it comes to whether or not to use underscores between the words in the >function names, we suggest an underscore after the extension name and then >none after that. That is the only way we can see of providing a scheme which >allows us to still use standard C functions (like isalpha()) without >breaking our own rules. I don't believe this will be seriously evaluated. THE unanimous agreement has been NoStudlyCaps, and I believe that means Seriously_NoStudlyCaps. -1 all the way to the Supreme Court. >When viewed in the light of the above (i.e. considering verbs, nouns etc), >even the bits of php which we might have thought were fairly clean (eg >mysql_...) are in need of a serious sorting out. > >Tony points out that the only way to convince anyone of the sanity of all >this is to generate the list of functions as they should be, but since there >are about 1600 functions in 84 extensions, if you managed one function every >20 seconds, then it would take you 9 hours to complete! And of course it >would then be shot down in flames :) [class_]getobjectvars? [func_]registershutdownfunction? NT. >Let the shooting begin. Here you are. :) Cynic