Skip to content

[Sync-En] userlandnaming: explain the identifier rules and refresh the examples #1266

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
lacatoire wants to merge 1 commit into
base: master
Choose a base branch
from
+53 −41
Open

[Sync-En] userlandnaming: explain the identifier rules and refresh the examples #1266

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
94 changes: 53 additions & 41 deletions appendices/userlandnaming.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,16 +1,15 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 0ad6aa08fb58311737ae61515d12651d7f14626e Maintainer: seros Status: ready -->
<!-- EN-Revision: 077012fff21b527d01ffde600ad3282098aa1c91 Maintainer: seros Status: ready -->
<!-- Reviewed: no Maintainer: andresdzphp -->
<appendix xml:id="userlandnaming" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<title>Guía de entorno de usuario para nombres</title>
<para>
<simpara>
La siguiente es una guía para saber cómo elegir el mejor nombre para los
identificadores del código del entorno del usuario PHP. Cuando se eligen
nombres para cualquier código que crea símbolos en el espacio de nombres global,
es importante tener en cuenta los siguientes lineamientos para evitar que en
futuras versiones de PHP estos choquen con los símbolos elegidos.
</para>
</simpara>

<section xml:id="userlandnaming.globalnamespace">
<title>Espacio de nombres global</title>
Expand All @@ -19,47 +18,53 @@
</para>

<itemizedlist>
<listitem><para>funciones</para></listitem>
<listitem><para>clases</para></listitem>
<listitem><para>interfaces</para></listitem>
<listitem><para>constantes (no constanstes de clase)</para></listitem>
<listitem><para>variables definidas fuera de funciones/métodos</para></listitem>
<listitem><simpara>funciones</simpara></listitem>
<listitem><simpara>clases</simpara></listitem>
<listitem><simpara>interfaces</simpara></listitem>
<listitem><simpara>traits</simpara></listitem>
<listitem><simpara>enumeraciones</simpara></listitem>
<listitem><simpara>constantes (no constantes de clase)</simpara></listitem>
<listitem>
<simpara>variables definidas fuera de funciones y métodos</simpara>
</listitem>
</itemizedlist>
</section>

<section xml:id="userlandnaming.rules">
<title>Reglas</title>
<para>
<simpara>
La siguiente lista muestra un resumen de los derechos que se reserva el
proyecto PHP para sí mismo, cuando elige los nombres para los nuevos
identificadores internos.
La guía definitiva son los
<link xlink:href="&url.userlandnaming.cs;">ESTÁNDARES DE CODIFICACION</link> oficiales:
</para>
<link xlink:href="&url.userlandnaming.cs;">estándares de codificación de PHP</link> oficiales:
</simpara>

<itemizedlist>
<listitem>
<para>
PHP es el propietario de el namespace de nivel superior, pero trata de
encontrar una descripción decente de nombres y evitar así futuros choques.
PHP es el propietario del espacio de nombres de nivel superior, pero trata de
encontrar nombres descriptivos correctos y de evitar cualquier choque evidente.
</para>
</listitem>
<listitem>
<para>
Los nombres de función usan guion bajo entre palabras, mientras que los
nombres de las clases usan las reglas <literal>camelCase</literal> o <literal>PascalCase</literal>.
</para>
<simpara>
Los nombres de función usan guion bajo entre palabras, los nombres de las
clases usan la notación <literal>PascalCase</literal>, y los nombres de los
métodos la notación <literal>camelCase</literal>.
</simpara>
</listitem>
<listitem>
<para>
<simpara>
PHP antepondrá a cualquier símbolo global de una extensión el nombre de
de la extensión. (En el pasado, han habido numerosas excepciones a esta regla).
la extensión. (En el pasado ha habido numerosas excepciones a esta regla,
por lo que algunos nombres existentes no llevan prefijo).
Ejemplos:
</para>
</simpara>

<itemizedlist>
<listitem><para><function>curl_close</function></para></listitem>
<listitem><para><function>mysql_query</function></para></listitem>
<listitem><simpara><function>curl_exec</function></simpara></listitem>
<listitem><simpara><function>mysqli_query</function></simpara></listitem>
<listitem><para>PREG_SPLIT_DELIM_CAPTURE</para></listitem>
<listitem><para>new DOMDocument()</para></listitem>
<listitem>
Expand All @@ -82,28 +87,32 @@
</itemizedlist>
</listitem>
<listitem>
<para>
PHP se reserva todos los simbolos que comienzan con <literal>__</literal>
como magicos. Es recomendado que no se creen simbolos que comiencen con
<literal>__</literal> en PHP a menos que se quiera usar una funcionalidad
magica documentada. Ejemplos:
</para>
<simpara>
PHP se reserva todos los símbolos que comienzan con <literal>__</literal>
como mágicos. Se recomienda que no se creen símbolos que comiencen con
<literal>__</literal> en PHP, a menos que se quiera usar una funcionalidad
mágica documentada. Ejemplos:
</simpara>
<itemizedlist>
<listitem><para><link linkend="object.get">__get()</link></para></listitem>
<listitem><para><function>__autoload</function></para></listitem>
<listitem>
<simpara><link linkend="object.get">__get()</link></simpara>
</listitem>
<listitem>
<simpara><link linkend="object.construct">__construct()</link></simpara>
</listitem>
</itemizedlist>
</listitem>
</itemizedlist>
</section>

<section xml:id="userlandnaming.tips">
<title>Consejos</title>
<para>
<simpara>
Con el fin de escribir código que funcione en el futuro, se recomienda no
colocar muchas variables, funciones o clases en el espacio de nombres global. Esto
prevendrá de conflictos de nombres con código de terceros así como con posibles
adiciones futuras al lenguaje.
</para>
</simpara>
<para>
Una manera común de evitar conflictos con nombres de funciones y clases es
añadirlos a su propio
Expand All @@ -116,24 +125,27 @@

namespace MiProyecto;

function mi_función() {
function mi_función()
{
return true;
}

\MiProyecto\mi_función();

?>
]]>
</programlisting>
</informalexample>
<para>
Esto todavía necesita que se mantenga la cuenta de los espacios de nombres ya utilizados, pero una vez
que se decido el espacio de nombres que se va a usar se pueden añadir todas las funciones y
clases e él sin tener que pensar más en conflictos.
</para>
<para>
<simpara>
Todavía es necesario llevar la cuenta de los espacios de nombres ya utilizados,
pero una vez elegido el espacio de nombres se pueden añadir a él todas las
funciones y clases sin tener que pensar más en conflictos.
</simpara>
<simpara>
Es una buena práctica limitar el número de variables añadidas al
ámbito global para evitar conflictos de nombres con código
de terceros.
</para>
</simpara>
<note>
<title>Ámbito de variables</title>
<para>
Expand Down