ZF-9187: backport r21160 to trunk

git-svn-id: http://framework.zend.com/svn/framework/standard/trunk@21161 44c647ce-9c0f-0410-b52a-842ac1e357ba

documentation/manual/en/ref/coding_standard.xml

@@ -189,6 +189,49 @@
                     that pre-date that version may not follow this rule, but will be renamed in
                     the future in order to comply.
                 </para>
+
+                <para>
+                    The rationale for the change is due to namespace usage. As we look towards Zend
+                    Framework 2.0 and usage of PHP 5.3, we will be using namespaces. The easiest way
+                    to automate conversion to namespaces is to simply convert underscores to the
+                    namespace separator -- but under the old naming conventions, this leaves the
+                    classname as simply "Abstract" or "Interface" -- both of which are reserved
+                    keywords in PHP. If we prepend the (sub)component name to the classname, we can
+                    avoid these issues.
+                </para>
+
+                <para>
+                    To illustrate the situation, consider converting the class
+                    <classname>Zend_Controller_Request_Abstract</classname> to use namespaces:
+                </para>
+
+                <programlisting language="php"><![CDATA[
+namespace Zend\Controller\Request;
+
+abstract class Abstract
+{
+    // ...
+}
+]]></programlisting>
+
+                <para>
+                    Clearly, this will not work. Under the new naming conventions, however, this
+                    would become:
+                </para>
+
+                <programlisting language="php"><![CDATA[
+namespace Zend\Controller\Request;
+
+abstract class RequestAbstract
+{
+    // ...
+}
+]]></programlisting>
+
+                <para>
+                    We still retain the semantics and namespace separation, while omitting the
+                    keyword issues; simultaneously, it better describes the abstract class.
+                </para>
             </note>
         </sect2>
 
@@ -216,7 +259,9 @@
                 <para>
                     This naming convention is new with version 1.9.0 of Zend Framework. Classes
                     that pre-date that version may not follow this rule, but will be renamed in
-                    the future in order to comply.
+                    the future in order to comply. See <link
+                        linkend="coding-standard.naming-conventions.abstracts">the previous
+                        section</link> for more information on the rationale for this change.
                 </para>
             </note>
         </sect2>