1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
|
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 288721 $ -->
<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
the camel case 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. (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><function>__get</function></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 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 suffixes) used in other
projects and advertise their chosen prefix (or suffix) 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:"~/.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
-->
|
