sean		Thu Jul 27 20:59:29 2006 UTC

  Added files:                 
    /phpdoc/en/appendices	userlandnaming.xml 

  Modified files:              
    /phpdoc	manual.xml.in 
    /phpdoc/entities	global.ent 
  Log:
  Userland Naming guide -- from Lukas Smith
  
http://cvs.php.net/viewvc.cgi/phpdoc/manual.xml.in?r1=1.213&r2=1.214&diff_format=u
Index: phpdoc/manual.xml.in
diff -u phpdoc/manual.xml.in:1.213 phpdoc/manual.xml.in:1.214
--- phpdoc/manual.xml.in:1.213	Sun Jan 15 00:47:45 2006
+++ phpdoc/manual.xml.in	Thu Jul 27 20:59:29 2006
@@ -2,7 +2,7 @@
 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
           "@srcdir@/dtds/dbxml-4.1.2/docbookx.dtd" [
 
-<!-- $Revision: 1.213 $ --> 
+<!-- $Revision: 1.214 $ --> 
 
 <!-- Add translated specific definitions and snippets --> 
 <!ENTITY % language-defs     SYSTEM "@srcdir@/@LANGDIR@/language-defs.ent"> 
@@ -172,6 +172,7 @@
   &appendices.transports;
   &appendices.comparisons;
   &appendices.tokens;
+  &appendices.userlandnaming;
   &appendices.about;
   &appendices.license;
   &global.function-index;
http://cvs.php.net/viewvc.cgi/phpdoc/entities/global.ent?r1=1.267&r2=1.268&diff_format=u
Index: phpdoc/entities/global.ent
diff -u phpdoc/entities/global.ent:1.267 phpdoc/entities/global.ent:1.268
--- phpdoc/entities/global.ent:1.267	Wed Jul 26 12:01:04 2006
+++ phpdoc/entities/global.ent	Thu Jul 27 20:59:29 2006
@@ -1,6 +1,6 @@
 <!-- -*- SGML -*-
 
- $Id: global.ent,v 1.267 2006/07/26 12:01:04 nlopess Exp $
+ $Id: global.ent,v 1.268 2006/07/27 20:59:29 sean Exp $
 
  Contains global "macros" for all the XML documents.
 
@@ -349,6 +349,7 @@
 <!ENTITY url.ultimatezip "http://www.ultimatezip.com/"> 
 <!ENTITY url.unicode "http://www.unicode.org/"> 
 <!ENTITY url.unicode.reports "http://www.unicode.org/unicode/reports/tr21/"> 
+<!ENTITY url.userlandnaming.cs "http://cvs.php.net/viewvc.cgi/php-src/CODING_STANDARDS?view
=annotate"> 
 <!ENTITY url.vb4linux "http://sourceforge.net/projects/vb4linux/"> 
 <!ENTITY url.vlife "http://www.vodafone.jp/english/live/"> 
 <!ENTITY url.w3.access "http://www.w3.org/WAI/GL/"> 

http://cvs.php.net/viewvc.cgi/phpdoc/en/appendices/userlandnaming.xml?view=markup&rev=1.1
Index: phpdoc/en/appendices/userlandnaming.xml
+++ phpdoc/en/appendices/userlandnaming.xml
<?xml version="1.0" encoding="utf-8"?> 
<!-- $Revision: 1.1 $ --> 
<appendix id="userlandnaming"> 
 <title> Userland Naming Guide</title>
 <para> 
  The following is a guide for how to best choose names for identifiers
  in PHP userland code. When choosing names for any code that creates symbols
  in the global namespace it is important to take into account the following
  guide lines to prevent future version of PHP to clash with userland code.
 </para> 

 <section id="userlandnaming.globalnamespace"> 
  <title> Global Namespace</title>
  <para> 
   Here is an overview of code constructs that go into the global namespace:
  </para> 

  <itemizedlist> 
   <listitem> <para>functions</para></listitem>
   <listitem> <para>classes</para></listitem>
   <listitem> <para>interfaces</para></listitem>
   <listitem> <para>constants (not class constants)</para></listitem>
   <listitem> 
    <para> variables defined outside of functions/methods</para>
   </listitem> 
  </itemizedlist> 
 </section> 

 <section id="userlandnaming.rules"> 
  <title> Rules</title>
  <para> 
   The following list gives an overview of what rights the PHP project
   reserves itself when choosing names for new internal identifiers. Note
   that the definitive guide is the official
   <ulink url="&url.userlandnaming.cs;"> CODING STANDARDS</ulink>:
  </para> 

  <itemizedlist> 
   <listitem> 
    <para> 
     PHP owns the top-level namespace but tries to find decent descriptive
     names and avoid any obvious clashes.
    </para> 
   </listitem> 
   <listitem> 
    <para> 
     Function names use underscores between words, while class names use
     the lower bumpy camel rule (there are some exceptions for older
     classes and functions).
    </para> 
   </listitem> 
   <listitem> 
    <para> 
     PHP will prefix any global symbols of an extension with the name of
     the extension (note that in the past there have been numerous
     exceptions to this rule). Examples:
    </para> 

    <itemizedlist> 
     <listitem> <para><function>curl_close</function></para></listitem>
     <listitem> <para><function>mysql_query</function></para></listitem>
     <listitem> <para>PREG_SPLIT_DELIM_CAPTURE</para></listitem>
     <listitem> <para>new DOMDocument()</para></listitem>
     <listitem> 
      <para> 
       <function> strpos</function> (example of a past mistake)
      </para> 
     </listitem> 
     <listitem> <para>new SplFileObject()</para></listitem>
    </itemizedlist> 
   </listitem> 
   <listitem> 
    <para> 
     Iterators and Exceptions are however simply postfixed with "Iterator"
     and "Exception". Examples:
    </para> 
    <itemizedlist> 
     <listitem> <para>ArrayIterator</para></listitem>
     <listitem> <para>LogicException</para></listitem>
    </itemizedlist> 
   </listitem> 
   <listitem> 
    <para> 
     PHP reserves all function names starting with __ as magical. It is
     recommended that you do not use function names with __ in PHP unless
     you want some documented magic functionality. Examples:
    </para> 
    <itemizedlist> 
     <listitem> <para><function>__get</function></para></listitem>
     <listitem> <para><function>__autoload</function></para></listitem>
    </itemizedlist> 
   </listitem> 
  </itemizedlist> 
 </section> 

 <section id="userlandnaming.tips"> 
  <title> Tips</title>
  <para> 
   In order to write future proof code it is therefore recommended to prefix
   (or postfix) anything that goes into the global namespace with a fairly
   random 3-4 letter prefix (or postfix) separated with an underscore. It is
   recommended that in order to prevent namespace clashes with other userland
   code that projects research existing prefixes (or postfixes) used in other
   projects and advertise their chosen prefix (or postfix) appropriately.
   Examples:
  </para> 

  <itemizedlist> 
   <listitem> <para>MyPx_someFunc()</para></listitem>
   <listitem> <para>Foo_Date</para></listitem>
   <listitem> <para>$asdf_dbh</para></listitem>
  </itemizedlist> 
 </section> 

</appendix> 
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->