sean Sat Aug 12 20:14:32 2006 UTC
Modified files:
/phpdoc/en/appendices userlandnaming.xml
Log:
grammar and markup
http://cvs.php.net/viewvc.cgi/phpdoc/en/appendices/userlandnaming.xml?r1=1.1&r2=1.2&diff_format=u
Index: phpdoc/en/appendices/userlandnaming.xml
diff -u phpdoc/en/appendices/userlandnaming.xml:1.1
phpdoc/en/appendices/userlandnaming.xml:1.2
--- phpdoc/en/appendices/userlandnaming.xml:1.1 Thu Jul 27 20:59:29 2006
+++ phpdoc/en/appendices/userlandnaming.xml Sat Aug 12 20:14:32 2006
@@ -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>
