Re: Advice from an outsider, hopefully useful

Hi Matt, Thanks for the thoughtful reply, I really appreciate the time taken. Matthew Weier O'Phinney wrote: > I'm going to point out here that the standards in question are all ones > that have been under *lengthy* review by the PEAR group (I believe some > of these date back as far as 2 years). Many of us in that meeting are I should let you know that I was present when they were originally proposed, and raised the same objections. It does not sit well that these were literally completely ignored, because this implies to me, perhaps unfairly, that dogma ruled over actually finding a solution. Sorry for the strength of my objection, but in my humble opinion this is a very, very dangerous path to take, and I feel a moral obligation to ensure that everyone here has really thought through the problem from every angle. > using either PEAR standards or derivatives of PEAR standards. The > meeting actually dates back to php|works last fall, when several of us > started discussing those standards and how we could get closure on them > so that our representative projects could move forward. And since then, where has the public debate been? Request for comments from the community at large? >> 1) The standard only mentions Underscored_Classnames, but has no mention >> of the truly standard way of doing things: Backslashed\Classnames. >> ns\name\Class\Name works just fine (the namespace/class barrier is >> obvious - the first capital letter is the start of the classname), and >> allows access to sub-namespaces using "relative namespace paths" (see >> the manual for clarification on this point, it was not present in early >> alphas of PHP 5.3). > > We actually did discuss this. The idea is that there is a vendor > namespace, and a component/package namespace. Within the latter, there > may be sub-components/packages nested arbitrarily deep, and this is the > recommended way forward. For BC and migration purposes, > Underscored_Classnames will still be allowed beneath the vendor\package > namespace, and follow the original PEAR1 standards. The standard does not explicitly mention this, which was my concern, because it definitely should mention it. I suggest this paragraph: "All classes, interfaces, and abstracts must begin with an uppercase character. They may contain additional capital letters and underscores. Any underscores in class names will be converted to the DIRECTORY_SEPARATOR when attempting to auto-load." be revised to include the final sentence "All namespace separators (T_NS_SEPARATOR) will be converted to the DIRECTORY_SEPARATOR when attempting to auto-load." and the 2nd sentence be revised to state "They may contain additional capital letters, underscores, and namespace separators (T_NS_SEPARATOR)." >> 2) Why is the package name present with underscores in the namespace >> name? I raised strong objections to this point over a year ago when it >> was first proposed to PEAR, and these seem to have been ignored. It >> will encourage coding mega-packages or weird hacks like empty shell >> classes (namespace ns/package;class Classname extends >> ns/split_package/Classname {}) for API BC compatibility. Far simpler, >> and much better, is to require vendor\ only, and to allow >> vendor-specific class name/package name mapping with a suggested format. > > The underscores in namespaces are primarily for readability when you > have a multi-word namespace. As an example, in ZF we have the component > Zend_CodeGenerator. When normalized, this becomes zend\codegenerator -- > which is somewhat harder to read. Underscores make this > zend\code_generator -- which offers better readability. > > The intention is not to allow for split packages -- it's simply for > readability. Was this possibility considered? zend\code\generator\CodeGenerator How about this one? zend\CodeGenerator or this one? Zend\CodeGenerator The last suggestion is the closest to existing PEAR coding standards (Zend_CodeGenerator becomes Zend/CodeGenerator.php) as followed by ZF as well. Adding the package name into the namespace and duplicating some of the information (zend\code_generator\CodeGenerator would be the class name under the standards in your example) is a huge change from the existing standards, and there are no reasons given. What problems exist that merit such a large change? The balancing of advantages to drawbacks is a crucial part of the rationale behind a standards change, exactly like the description below of abstract/interface naming. The intention may not have been to allow for split packages, but that simply validates my concern - it means that this was never considered, even though it was brought up as a major objection within PEAR when the original proposal was raised. The reasoning I have heard for adding the package name is that it simplifies svn:externals. However, this does not match up with my experience. Because it is simple to include a subdirectory within a package using svn:externals, and to give it an arbitrary name, the only challenge is an autoloader mapping to the internal structure, which is no challenge at all. >> 3) Arguments or standards suggestions that were ruled out need to be >> documented as well, or you'll find that newcomers talk in circles >> re-hashing everything. > > Good point. I'll point out one of those now. > > Regarding the decision on naming conventions surrounding abstract > classes and interfaces, a strong group of us were of the mindset that > these should be named generically, without hungarian notation. However, > in practice, this becomes very difficult, particularly for non-native > English speakers. As an example, interface names should usually describe > capabilities (Count_able_, Read_able_, etc) and are thus best written as > adjectives. Many nouns, however, do not map easily to adjectives: a > "Personable" does not imply an interface describing a person; > "Resource" could be either an interface *or* an abstract class; etc. > These nuances are even harder to understand if you do not have an > excellent grasp of English -- and in many of our projects, native > English speakers are actually the exception. As a result, we decided > that suffixing the class with Abstract and Interface was the best path > forward: PersonInterface, ResourceAbstract. While this does not satisfy > the academics amongst us, it's a pragmatic resolution. Sounds good. I assume by hungarian notation you're talking about the convention of IInterfaceName/AAbstractName. I think the approach settled on works fine, although I've found it makes it easier for me to find my interfaces when they all start with the same letter, but I can adjust to this new way quite easily :). >> Let's also not ignore ezComponents or pecl/automap solution to locating >> classes - a static array mapping class name to file. This is much more >> performant in autoload (no include_path search), but requires the extra >> step of generating the static array. Thus the standards should mention >> that vendors may provide a vendor-specific autoload which should be >> loaded before the standardized one. > > We're recommending a common autoloader -- but that shouldn't imply that > you can't use other autoloading strategies. The main reason for > suggesting a common autoloader, and particularly for having one > included in the SPL, is to encourage interoperability between frameworks > and libraries that follow these common standards. But, as you note, > other strategies exist, and due to the nature of spl_autoload, can be > used in conjunction with this solution. I would recommend that this last paragraph be slipped into the standards verbatim, that's all I'm talking about. It shows a completeness of consideration in an inclusive manner. I am sure that the autoloader stuff was mentioned in the meeting, but it completely changes the tone of the standard to include it. Without this paragraph it sounds like "one autoloader to rule them all" and with this paragraph it sounds like "we're making things easier for you to inter-operate." :) Thanks, Greg