Skip to content

userlandnaming.xml Explain the identifier, symbol; personalization #4032

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

userlandnaming.xml Explain the identifier, symbol; personalization #4032

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 21 additions & 13 deletions appendices/userlandnaming.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,10 +3,12 @@
<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
The following is a guide for how to best choose names for identifiers (or
the part of lexical tokens also called a symbols),
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
in the <link linkend="features.gc.refcounting-basics">symbol table</link>
of the global namespace, it is important to take into account the following
guidelines to prevent future versions of PHP from clashing with user
symbols.
</para>

Expand All @@ -20,9 +22,11 @@
<listitem><para>functions</para></listitem>
<listitem><para>classes</para></listitem>
<listitem><para>interfaces</para></listitem>
<listitem><para>traits</para></listitem>
<listitem><para>enumerations</para></listitem>
<listitem><para>constants (not class constants)</para></listitem>
<listitem>
<para>variables defined outside of functions/methods</para>
<para>variables defined outside of functions and methods</para>
</listitem>
</itemizedlist>
</section>
Expand All @@ -33,7 +37,7 @@
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>:
<link xlink:href="&url.userlandnaming.cs;">Coding Standards</link>:
</para>

<itemizedlist>
Expand All @@ -47,14 +51,15 @@
<para>
Function names use underscores between words, while class names use
both the <literal>camelCase</literal> and <literal>PascalCase</literal>
rules.
rules of the identifiers format style.
</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:
the extension. (In the past, there have been numerous exceptions to this rule
which have resulted in identifiers that do not follow the naming rules.)
Examples:
</para>

<itemizedlist>
Expand Down Expand Up @@ -99,7 +104,7 @@
<section xml:id="userlandnaming.tips">
<title>Tips</title>
<para>
In order to write future-proof code, it is recommended that you don't
In order to write future-proof code, it is recommended don't
place many variables, functions or classes in the global namespace. This will
prevent naming conflicts with 3rd party code as well as possible
future additions to the language.
Expand All @@ -116,18 +121,21 @@

namespace MyProject;

function my_function() {
function my_function()
{
return true;
}

\MyProject\my_function();

?>
]]>
</programlisting>
</informalexample>
<para>
This still needs you to keep track of already used namespaces, but once you
have decided on a namespace you will be using you can add all functions and
classes to it without having to think about conflicts again.
This still needs to keep track of already used namespaces, but once programmer
has decided on a namespace that will be using then functions and
classes can be added to it without having to think about conflicts again.
</para>
<para>
It is considered best practice to limit the number of variables added to
Expand Down