Userland Naming guide -- from Lukas Smith

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@217209 c90b9560-bf6c-de11-be94-00142212c4b1
This commit is contained in:
Sean Coates 2006-07-27 20:59:29 +00:00
parent 1729d39eea
commit f58c67a595

View file

@ -0,0 +1,135 @@
<?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
-->