php-doc-en/appendices/userlandnaming.xml

168 lines
5.3 KiB
XML
Raw Permalink Normal View History

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<appendix xml:id="userlandnaming" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<title>Userland Naming Guide</title>
<para>
The following is a guide for how to best choose names for identifiers
in userland PHP code. When choosing names for any code that creates symbols
in the global namespace, it is important to take into account the following
guidelines to prevent future versions of PHP from clashing with your
symbols.
</para>
<section xml: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 xml:id="userlandnaming.rules">
<title>Rules</title>
<para>
The following list gives an overview of which rights the PHP project
reserves for itself, when choosing names for new internal identifiers.
The definitive guide is the official
<link xlink:href="&url.userlandnaming.cs;">CODING STANDARDS</link>:
</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
both the <literal>camelCase</literal> and <literal>PascalCase</literal>
rules.
</para>
</listitem>
<listitem>
<para>
PHP will prefix any global symbols of an extension with the name of
the extension. (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
"<literal>Iterator</literal>" and "<literal>Exception</literal>."
Examples:
</para>
<itemizedlist>
<listitem><para><classname>ArrayIterator</classname></para></listitem>
<listitem><para><classname>LogicException</classname></para></listitem>
</itemizedlist>
</listitem>
<listitem>
<para>
PHP reserves all symbols starting with <literal>__</literal>
as magical. It is recommended that you do not create symbols starting
with <literal>__</literal> in PHP unless
you want to use documented magical functionality. Examples:
</para>
<itemizedlist>
<listitem><para><link linkend="object.get">__get()</link></para></listitem>
<listitem><para><function>__autoload</function></para></listitem>
</itemizedlist>
</listitem>
</itemizedlist>
</section>
<section xml:id="userlandnaming.tips">
<title>Tips</title>
<para>
In order to write future-proof code, it is recommended that you don't
place many variables, functions or classes in the global namespace. This will
prevent naming conflicts with 3rd party code as well as possible
future additions to the language.
</para>
<para>
One common way to prevent naming conflicts of functions and classes is to
add them to their own dedicated
<link linkend="language.namespaces">namespace</link>.
</para>
<informalexample>
<programlisting role="php">
<![CDATA[
<?php
namespace MyProject;
function my_function() {
return true;
}
\MyProject\my_function();
]]>
</programlisting>
</informalexample>
<para>
This still needs you to keep track of already used namespaces, but once you
have decided on a namespace you will be using you can add all functions and
classes to it without having to think about conflicts again.
</para>
<para>
It is considered best practice to limit the number of variables added to
the global scope in order to prevent naming conflicts with 3rd party
code.
</para>
<note>
<title>Variable scoping</title>
<para>
Because of PHP's <link linkend="language.variables.scope">scoping rules</link>
variables defined inside functions and methods are not in the global scope
and as such cannot conflict with other variables defined in the global scope.
</para>
</note>
</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:"~/.phpdoc/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
-->