grammar and markup

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@218051 c90b9560-bf6c-de11-be94-00142212c4b1
This commit is contained in:
Sean Coates 2006-08-12 20:14:32 +00:00
parent f0144aed21
commit bdd16af9be

View file

@ -1,12 +1,13 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 1.1 $ -->
<!-- $Revision: 1.2 $ -->
<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.
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 id="userlandnaming.globalnamespace">
@ -29,9 +30,9 @@
<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
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
<ulink url="&url.userlandnaming.cs;">CODING STANDARDS</ulink>:
</para>
@ -52,8 +53,8 @@
<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:
the extension. (In the past, there have been numerous
exceptions to this rule.) Examples:
</para>
<itemizedlist>
@ -71,19 +72,21 @@
</listitem>
<listitem>
<para>
Iterators and Exceptions are however simply postfixed with "Iterator"
and "Exception". Examples:
Iterators and Exceptions are however simply postfixed with
"<literal>Iterator</literal>" and "<literal>Exception</literal>."
Examples:
</para>
<itemizedlist>
<listitem><para>ArrayIterator</para></listitem>
<listitem><para>LogicException</para></listitem>
<listitem><para><literal>ArrayIterator</literal></para></listitem>
<listitem><para><literal>LogicException</literal></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:
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><function>__get</function></para></listitem>
@ -96,12 +99,12 @@
<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
In order to write future-proof code, it is recommended that you prefix
(or suffix) anything that goes into the global namespace with an uncommon
3-4 letter prefix (or suffix) 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.
code that projects research existing prefixes (or suffixes) used in other
projects and advertise their chosen prefix (or suffix) appropriately.
Examples:
</para>