mirror of
https://github.com/sigmasternchen/php-doc-en
synced 2025-03-15 16:38:54 +00:00
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
parent
1729d39eea
commit
f58c67a595
1 changed files with 135 additions and 0 deletions
135
appendices/userlandnaming.xml
Normal file
135
appendices/userlandnaming.xml
Normal 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
|
||||
-->
|
||||
Loading…
Reference in a new issue