appendices/userlandnaming.xml
0ad6aa08fb58311737ae61515d12651d7f14626e
0ad6aa08fb58311737ae61515d12651d7f14626e
...
...
@@ -99,20 +99,49 @@
99
99
<section xml:id="userlandnaming.tips">
100
100
<title>Tips</title>
101
101
<para>
102
-
In order to write future-proof code, it is recommended that you prefix
103
-
(or suffix) anything that goes into the global namespace with an uncommon
104
-
3-4 letter prefix (or suffix) separated with an underscore. It is
105
-
recommended that in order to prevent namespace clashes with other userland
106
-
code that projects research existing prefixes (or suffixes) used in other
107
-
projects and advertise their chosen prefix (or suffix) appropriately.
108
-
Examples:
102
+
In order to write future-proof code, it is recommended that you don't
103
+
place many variables, functions or classes in the global namespace. This will
104
+
prevent naming conflicts with 3rd party code as well as possible
105
+
future additions to the language.
109
106
</para>
107
+
<para>
108
+
One common way to prevent naming conflicts of functions and classes is to
109
+
add them to their own dedicated
110
+
<link linkend="language.namespaces">namespace</link>.
111
+
</para>
112
+
<informalexample>
113
+
<programlisting role="php">
114
+
<![CDATA[
115
+
<?php
110
116
111
-
<itemizedlist>
112
-
<listitem><para>MyPx_someFunc()</para></listitem>
113
-
<listitem><para>Foo_Date</para></listitem>
114
-
<listitem><para>$asdf_dbh</para></listitem>
115
-
</itemizedlist>
117
+
namespace MyProject;
118
+
119
+
function my_function() {
120
+
return true;
121
+
}
122
+
123
+
\MyProject\my_function();
124
+
]]>
125
+
</programlisting>
126
+
</informalexample>
127
+
<para>
128
+
This still needs you to keep track of already used namespaces, but once you
129
+
have decided on a namespace you will be using you can add all functions and
130
+
classes to it without having to think about conflicts again.
131
+
</para>
132
+
<para>
133
+
It is considered best practice to limit the number of variables added to
134
+
the global scope in order to prevent naming conflicts with 3rd party
135
+
code.
136
+
</para>
137
+
<note>
138
+
<title>Variable scoping</title>
139
+
<para>
140
+
Because of PHP's <link linkend="language.variables.scope">scoping rules</link>
141
+
variables defined inside functions and methods are not in the global scope
142
+
and as such cannot conflict with other variables defined in the global scope.
143
+
</para>
144
+
</note>
116
145
</section>
117
146
118
147
</appendix>
119
148