[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