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
-->
