[drift] About function renaming

As the subject states, this is quite a drift. Nevertheless it provides insights on actual events going on in my environment and notes taken from the list that could help us all. If you don't want to read all the background information, jump to "Where do we go from here ?" (two stars below). For the last few weeks, the PHP-QAT (re)started talking about functional name space in PHP. The PEAR list has been following a parallel discussion on this topic for some time now. Today the thread hit my desk and our dev-open-space at MM... Let's begin with the PEAR list. The objectives of PEAR require a coherent namespace. JavaDoc comes as the choice for documenting PHP code. Recent discussion has shown funny comments -- order of arguments in DB::common::trigger_error(), Andi is '>', Colin's replying :

Is this what was decided for PEAR? Because usually these kind of functions are: func(error_level, error_message). I don't really mind but it's something to consider. It looks odd to me this way around :)

This isn't a PEAR thing. I was just fixing it to work with PHP. Take a look at the proto in Zend/zend_builtin_functions.c <grin> -- and more expert ones, like Chuck refusing curly braces around method names because it doesn't mean anything on the semantics level [unnecessary] while Aaron prefers them for debugging and readability, especially for new programmers. Those three examples show how diverse the approach can be and that every detail can count. Assuming there is always an error_code (or errno as we call it), it should be the first argument, followed by an eventual error_msg (message is far too long. ;-) But then, 'builtin' functions use the other -- odd -- way around. Here... There must be some reason ? Probably, on a logical point of view, you begin with an error_code and then add something for the human being ; actually, you code and start writing what will make sense for you when testing, not a meaningless digit. So, would this be all about finding a smooth path between efficiency in writing and reading PHP code ? Where the logical, organizational stance should be quiet and allow different approches, while keeping a strong coherence for easy remembering (please don't do French, it's filled with so many exceptions ; that makes it beautiful when well-written but horrendous if not). A few days ago I started to get bored with all that pointless renaming thread on PHP-QA. I wanted to get it done, stop discussing points before more important one would even have the chance to pop up while trying new names... The 'Quizz' (http://marc.theaimsgroup.com/?l=php-qa&m=98173901803916&w=2) generated 5 replies and not a single common pattern except that nobody proposed another example. I found some strong reactions to some notations... But on both sides (definitely yes and definitely not). Curly braces seem stuck to the function name, even someone told me in example 'm' they were in the wrong place. But again, no unanimity on that either. StudlyCaps ('j') were bashed but by one who uses them all the time. studlyCaps ('i') were ok most of the time. no_studly_caps is preferred but we don't know if it's no_studlycaps, no_studlyCaps or no_studly_caps... The lesson here is : it's a question of habit. In PEAR, the consensus isn't achieved yet. We find : - ALLCAPS acronyms - 3 types of Class names : 1. Begins with a CAPITAL letter eventually followed by an underscore '_' followed by a CAPITAL letter followed by lowercase letters (except for acronyms) E.g.: DB, DB_Error 2. lowercase (with underscores ? (and CAPITAL acronyms ?)) E.g.: DB_result, DB::mysql 3. StudlyCaps (see File/) - Method names use studlyCaps ('i') (except for Acronyms) <-- That seems to hit a consensus E.g.: DB::parseDSN(), File_SearchReplace::setReplace() - Variables are lowercase, may use underscores. - CONSTANTS_ARE_ALLCAPS * Today, one of my co-workers approached me on the topic of a standard naming scheme, as their team has grown to 8 persons and naming habits began to strike. How did you name that function ? Can you spell it ? Their files show all sorts of names we have seen in PEAR or in PHP builtin functions. Two of them, from the original team use studlyCaps ('i') so why not extend them to the whole team as most code has already been written like that.. Not innocent that renaming functions thread. Hence, this email was sent as a copy to my co-workers. * Where do we go from here ? The hard way (arbitrary but coherent): - Constants are ALLCAPS_UNDERSCORE_SEPARATED - Acronyms are ALLCAPS - Root-level-class (aka Packages) names are Studly_Caps (Most are acronyms anyway) - Other class names are studlyCaps - Function names are underscore_separated, eventually prefixed with lowercase extension ('mysql_') or lowercase extension prefix ('str_') - Class methods are studlyCaps - variables are free, mostly following function scheme (without any default prefix) Case sensitivity is not an issue here. PHP has grown without case sensitivity and most PHP programmers are used to it. Thanks it's not required, regarding PEAR. I can't think of another way to do it : - forcing case sensitivity would kill us all IMO as you would need to learn far more stuff to get your work done. Debugging "I" instead of "i" would just be a waste of time... - Case sensitivity should be kept for inter-operability between PEAR packages, as a mean to enforce "good coding style" and thus PEAR must be the place where best naming practice occurs. Hence case sensitivity would be forced on the user lvel, not hardcoded. For example, it can work without the right case or the right function alias, but issue a warning if it's the case, and then CANNOT be included in the PEAR. Or, some Package may have hardcoded calls to other packages, thus forcing the called package to follow the standard. That may seem a bit constraining but it will help on the long term to build a consensus around a recommended (if not official) coding style. - Packages may differ from other class names but if they do, they shouldn't be ALLCAPS as Constants and Acronyms use that already. PEAR people would like to tell us if they think separating Packages from other classes is good or not (I chose this after having a look at the PEAR arborescence). - Separating PHP_OOP approach from usual functional approach might help make the difference between the two. I find it normal that OOP is more rigorous in naming functions than any other approach as it's structurally more integrated (my 2cts). - OOP programmers coming from Java would be more productive if they can find some similarities. On the other hand beginners would be more at ease with functions that mimick those in the manual, or simply extension coders would be happy if they have an idea of what their API should be like. And as Phil nicely put it, "Lower case only is the thing which will give us compatibility with the standard C functions namespace." So, to summarize, we have 3 differents namespaces to organize : - basic PHP functions (more in the way C does, plus the extension prefixing) - PEAR (aka the OOP part of PHP) - user defined functions as used in examples for the manual or sample applications that don't use PEAR packages. Those should respectively follow : - lower case : [extension name or prefix]_[descriptive but short function name] - mixed : Package, Package_Name, class, className, method, methodName, var, var_name - func_name There are other issues to take into account, such as special case functions or vars (prefixed with one or more '_' ?), argument order (thanks to Phil for pointing the args specifities in ext/mysql), etc. Thanks for your attention, it's Valentine's day and even if that doesn't mean anything, it's 22:12 here and I'm hungry ;-) hellekin