repo_zf1/documentation/manual/es/ref/coding_standard.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 20096 -->
    <!-- Reviewed: no -->
<appendix id="coding-standard">
    <title>Estándares de codificación de Zend Framework para PHP</title>
    <sect1 id="coding-standard.overview">
        <title>Introducción</title>

        <sect2 id="coding-standard.overview.scope">
            <title>Alcance</title>

            <para> Este documento provee las pautas para el formato del código y
                la documentación a personas y equipos que contribuyan con Zend
                Framework. Muchos de los desarrolladores que usan Zend Framework
                han encontrado útiles estos estándares debido a que el estilo de
                su código permanece consistente con otros códigos fuente basados
                en Zend Framework. También debe resaltarse que especificar
                completamente los estándares de código requiere un esfuerzo
                significativo. </para>
            <note>
                <para> Nota: A veces, los desarrolladores consideran el
                    establecimiento de estándares más importante que lo que el
                    estándar sugiere realmente al nivel más detallado de diseño.
                    Estas pautas en los estándares de código de Zend Framework
                    han demostrado funcionar bien en otros projectos de Zend
                    Framework. Puede modificar estos estándares o usarlos en
                    conformidad con los términos de nuestra <ulink
                        url="http://framework.zend.com/license">licencia</ulink>
                </para>
            </note>

            <para> Temas incluídos en los estándares de código de Zend
                Framework: </para>

            <itemizedlist>
                <listitem>
                    <para> Dar formato a archivos <acronym>PHP</acronym>
                    </para>
                </listitem>

                <listitem>
                    <para>Convenciones de nombrado</para>
                </listitem>

                <listitem>
                    <para>Estilo de código</para>
                </listitem>

                <listitem>
                    <para>Documentación integrada</para>
                </listitem>
            </itemizedlist>

        </sect2>

        <sect2 id="coding-standard.overview.goals">
            <title>Objetivos</title>
            <para> Los estándares de código resultan importantes en cualquier
                proyecto de desarrollo, pero son especialmente importantes
                cuando muchos desarrolladores trabajan en el mismo proyecto. Los
                estándares de código ayudan a asegurar que el código tenga una
                alta calidad, menos errores, y pueda ser mantenido fácilmente.
            </para>
        </sect2>
    </sect1>

    <sect1 id="coding-standard.php-file-formatting">
        <title>Formato de archivos PHP</title>

        <sect2 id="coding-standard.php-file-formatting.general">
            <title>General</title>

            <para> Para archivos que contengan únicamente código
                    <acronym>PHP</acronym> , la etiqueta de cierre ("?>") no
                está permitida. No es requerida por <acronym>PHP</acronym> , y
                omitirla evita la inyección de espacios en blanco en la
                respuesta. </para>

            <note>
                <para>
                    <emphasis>IMPORTANTE:</emphasis> La inclusión de datos
                    binarios arbitrarios permitidos por
                        <methodname>__HALT_COMPILER()</methodname> está
                    prohibida en los archivos <acronym>PHP</acronym> de Zend
                    Framework, así como en cualquier fichero derivado. El uso de
                    esta característica sólo está permitido en algunos scripts
                    de instalación. </para>
            </note>
        </sect2>

        <sect2 id="coding-standard.php-file-formatting.indentation">
            <title>Identación</title>

            <para>La identación suele estar compuesta por 4 espacios. Las
                tabulaciones no están permitidas.</para>
        </sect2>

        <sect2 id="coding-standard.php-file-formatting.max-line-length">
            <title>Tamaño máximo de línea</title>

            <para> La longitud recomendable para una línea de código es de 80
                caracteres. Esto significa que los desarrolladores de Zend
                deberían intentar mantener cada línea de su código por debajo de
                los 80 caracteres, siempre que sea posible. No obstante, líneas
                más largas pueden ser aceptables en algunas situaciones. El
                tamaño máximo de cualquier línea de código
                    <acronym>PHP</acronym> es de 120 caracteres. </para>
        </sect2>

        <sect2 id="coding-standard.php-file-formatting.line-termination">
            <title>Final de línea</title>

            <para> El Final de Línea sigue la convención de archivos de texto
                Unix. Las líneas deben acabar con un carácter linefeed (LF). Los
                caracteres Linefeed están representados con el número 10
                ordinal, o el número 0x0A hexadecimal. </para>

            <para> Nota: No use retornos de carro (carriage returns, CR) como en
                las fuentes de Apple (0x0D) o la combinación de retorno de carro
                - linefeed ( <acronym>CRLF</acronym> ) estandar para sistemas
                operativos Windows (0x0D, 0x0A). </para>
        </sect2>
    </sect1>

    <sect1 id="coding-standard.naming-conventions">
        <title>Convenciones de Nombres</title>

        <sect2 id="coding-standard.naming-conventions.classes">
            <title>Clases</title>

            <para> Zend Framework se estandariza una convencion de nombres de
                clases donde los nombres de las clases apuntan directamente a
                las carpetas en las que estan contenidas. La carpeta raiz de la
                biblioteca estandar de Zend Framework es la carpeta "Zend/",
                mientras que la carpeta raíz de las bibliotecas extra de Zend
                Framework es la carpeta "ZendX/". Todas las clases de Zend
                Framework están almacenadas jerárquicamente bajo estas carpetas
                raíz. </para>

            <para> Los nombres de clases pueden contener sólo caracteres
                alfanuméricos. Los números están permitidos en los nombres de
                clase, pero desaconsejados en la mayoría de casos. Las barras
                bajas (_) están permitidas solo como separador de ruta (el
                archivo " <filename>Zend/Db/Table.php</filename> " debe apuntar
                al nombre de clase " <classname>Zend_Db_Table</classname> "). </para>

            <para> Si el nombre de una clase esta compuesto por mas de una
                palabra, la primera letra de cada palabra debe aparecer en
                mayúsculas. Poner en mayúsculas las letras siguientes no está
                permitido, ej: "Zend_PDF" no está permitido, mientras que "
                    <classname>Zend_Pdf</classname> " es admisible. </para>

            <para> Estas convenciones definen un mecanismo de pseudo-espacio de
                nombres para Zend Framework. Zend Framework adoptará la
                funcionalidad <acronym>PHP</acronym> de espacio de nombres
                cuando esté disponible y sea factible su uso en las aplicaciones
                de nuestros desarrolladores. </para>

            <para> Vea los nombres de clase en las bibliotecas estandar y
                adicionales (extras) como ejemplos de esta convención de
                nombres. </para>

            <note>
                <para>
                    <emphasis>IMPORTANTE:</emphasis> El código que deba
                    distribuirse junto a las bibliotecas de Zend Framework, pero
                    no forma parte de las bibliotecas estándar o extras de Zend
                    (e.g.: código o bibliotecas que no estén distribuídas por
                    Zend) no puede empezar nunca por "Zend_" o "ZendX_". </para>
            </note>
        </sect2>

        <sect2 id="coding-standard.naming-conventions.abstracts">
            <title>Clases Abstractas </title>

            <para> En general, las clases abstractas siguen las mismas
                convenciones que las <link
                    linkend="coding-standard.naming-conventions.classes"
                    >clases</link> , con una regla adicional: Los nombres de las
                clases abstractas deben acabar con el término, "Abstract", y ese
                término no debe ser precedida por un guión bajo. Ejemplo,
                    <classname>Zend_Controller_Plugin_Abstract</classname> es
                considerado un nombre no válido, pero
                    <classname>Zend_Controller_PluginAbstract</classname> o
                    <classname>Zend_Controller_Plugin_PluginAbstract</classname>
                serian nombres válidos. </para>

            <note>
                <para> Esta convención de nombres es nuevo con la versión 1.9.0
                    de Zend Framework. Las clases que preceden aquella versión
                    no pueden seguir esta regla, pero serán renombradas en el
                    futuro a fin de cumplir la regla. </para>
            </note>
        </sect2>

        <sect2 id="coding-standard.naming-conventions.interfaces">
            <title>Interfaces</title>

            <para> En general, las clases abstractas siguen las mismas
                convenciones que las <link
                    linkend="coding-standard.naming-conventions.classes"
                    >classes</link> , con una regla adicional: Los nombres de
                las interfaces opcionalmente pueden acabar con el término,
                "Interface",pero término no debe ser precedida por un guión
                bajo. Ejemplo,
                    <classname>Zend_Controller_Plugin_Interface</classname> es
                considerado un nombre no válido, pero
                    <classname>Zend_Controller_PluginInterface</classname> o
                    <classname>Zend_Controller_Plugin_PluginInterface</classname>
                serian nombres válidos. </para>

            <para> Si bien esta regla no es necesaria, se recomienda
                encarecidamente su uso, ya que proporciona una buena refrencia
                visual a los desarrolladores, como saber que archivos contienen
                interfaces en lugar de clases. </para>

            <note>
                <para> Esta convención de nombres es nuevo con la versión 1.9.0
                    de Zend Framework. Las clases que preceden aquella versión
                    no pueden seguir esta regla, pero serán renombradas en el
                    futuro a fin de cumplir la regla. </para>
            </note>
        </sect2>

        <sect2 id="coding-standard.naming-conventions.filenames">
            <title>Nombres de Archivo</title>

            <para> Para cualquier otro archivo, sólo caracteres alfanuméricos,
                barras bajas (_) y guiones (-) están permitidos. Los espacios en
                blanco están estrictamente prohibidos. </para>

            <para> Cualquier archivo que contenga código <acronym>PHP</acronym>
                debe terminar con la extensión " <filename>.php</filename> ",
                con la excepción de los scripts de la vista. Los siguientes
                ejemplos muestran nombres de archivo admisibles para clases de
                Zend Framework..: </para>
            <programlisting language="php"><![CDATA[
Zend/Db.php

Zend/Controller/Front.php

Zend/View/Helper/FormRadio.php
]]></programlisting>
            <para> Los nombres de archivo deben apuntar a nombres de clases como
                se describe arriba. </para>
        </sect2>

        <sect2 id="coding-standard.naming-conventions.functions-and-methods">
            <title>Funciones y Métodos</title>

            <para> Los nombres de funciones pueden contener únicamente
                caracteres alfanuméricos. Las guiones bajos (_) no estan
                permitidos. Los números están permitidos en los nombres de
                función pero no se aconseja en la mayoría de los casos. </para>

            <para> Los nombres de funciones deben empezar siempre con una letra
                minúscula. Cuando un nombre de función consiste en más de una
                palabra, la primera letra de cada nueva palabra debe estar en
                mayúsculas. Esto es llamado comúnmente como formato "camelCase". </para>

            <para> Por norma general, se recomienda la elocuencia. Los nombres
                de función deben ser lo suficientemente elocuentes como para
                describir su propósito y comportamiento. </para>

            <para> Estos son ejemplos de nombres de funciones admisibles: </para>
            <programlisting language="php"><![CDATA[
filterInput()

getElementById()

widgetFactory()
]]></programlisting>

            <para> Para la programación orientada a objetos, los métodos de
                acceso para las instancias o variables estáticas deben ir
                antepuestos con un "get" o un "set". Al implementar el patron de
                diseño, tales como el patrón singleton o el patrón factory, el
                nombre del método debe contener en la práctica el nombre del
                patrón para describir su comportamiento de forma más completa. </para>

            <para> Para el caso en que los métodos son declarados con el
                modificador "private" o "protected", el primer carácter del
                nombre de la variable debe ser una barra baja (_). Este es el
                único uso admisible de una barra baja en un nombre de método.
                Los métodos declarados como públicos no deberían contener nunca
                una barra baja. </para>

            <para> Las funciones de alcance global (también llamadas "funciones
                flotantes") están permitidas pero desaconsejadas en la mayoría
                de los casos. Considere envolver esas funciones en una clase
                estática. </para>
        </sect2>

        <sect2 id="coding-standard.naming-conventions.variables">
            <title>Variables</title>

            <para> Los nombres de variables pueden contener caracteres
                alfanuméricos. Las barras bajas (_) no están permitidas. Los
                números están permitidos en los nombres de variable pero no se
                aconseja en la mayoría de los casos. </para>

            <para> Para las variables de instancia que son declaradas con el
                modificador "private" o "protected", el primer carácter de la
                variable debe ser una única barra baja (_). Este es el único
                caso admisible de una barra baja en el nombre de una variable.
                Las variables declaradas como "public" no pueden empezar nunca
                por barra baja. </para>

            <para> Al igual que los nombres de funciones (ver sección 3.3), los
                nombres de variables deben empezar siempre con una letra en
                minúscula y seguir la convención "camelCaps". </para>

            <para> Por norma general, se recomienda la elocuencia. Las variables
                deberían ser siempre tan elocuentes como prácticas para
                describir los datos que el desarrollador pretende almacenar en
                ellas. Variables escuetas como " <varname>$i</varname> " y "
                    <varname>$n</varname> " están desaconsejadas, salvo para el
                contexto de los bucles más pequeños. Si un bucle contiene más de
                20 líneas de código, las variables de índice deberían tener
                nombres más descriptivos. </para>
        </sect2>

        <sect2 id="coding-standard.naming-conventions.constants">
            <title>Constantes</title>

            <para> Las constantes pueden contener tanto caracteres alfanuméricos
                como barras bajas (_). Los números están permitidos. </para>

            <para> Todos las letras pertenecientes al nombre de una constante
                deben aparecer en mayúsculas. </para>

            <para> Las palabras dentro del nombre de una constante deben
                separarse por barras bajas (_). Por ejemplo,
                    <constant>EMBED_SUPPRESS_EMBED_EXCEPTION</constant> está
                permitido, pero
                    <constant>EMBED_SUPPRESSEMBEDEXCEPTION</constant> no. </para>

            <para> Las constantes deben ser definidas como miembros de clase con
                el modificador "const". Definir constantes en el alcance global
                con la función "define" está permitido pero no recomendado.
            </para>
        </sect2>
    </sect1>

    <sect1 id="coding-standard.coding-style">
        <title>Estilo de código</title>

        <sect2 id="coding-standard.coding-style.php-code-demarcation">
            <title>Demarcación de código PHP</title>

            <para> El código <acronym>PHP</acronym> debe estar delimitado
                siempre por la forma completa de las etiquetas
                    <acronym>PHP</acronym> estándar: </para>

            <programlisting language="php"><![CDATA[
<?php

?>
]]></programlisting>

            <para> Las etiquetas cortas (short tags) no se permiten nunca. Para
                archivos que contengan únicamente código <acronym>PHP</acronym>
                , la etiqueta de cierrre debe omitirse siempre (Ver <xref
                    linkend="coding-standard.php-file-formatting.general"/> ).
            </para>
        </sect2>

        <sect2 id="coding-standard.coding-style.strings">
            <title>Cadenas de Caracteres </title>

            <sect3 id="coding-standard.coding-style.strings.literals">
                <title>Cadenas Literales de Caracteres</title>

                <para> Cuando una cadena es literal (no contiene sustitución de
                    variables), el apóstrofo o "comilla" debería ser usado
                    siempre para delimitar la cadena: </para>

                <programlisting language="php"><![CDATA[
$a = 'Example String';
]]></programlisting>

            </sect3>

            <sect3
                id="coding-standard.coding-style.strings.literals-containing-apostrophes">
                <title>Cadenas Literales de Caracteres que Contengan
                    Apóstrofos</title>

                <para> Cuando una cadena literal de caracteres contega
                    apóstrofos, es permitido delimitar la cadena de caracteres
                    con "comillas dobles". Esto es especialmente útil para
                    sentencias <constant>SQL</constant> : </para>
                <programlisting language="php"><![CDATA[
$sql = "SELECT `id`, `name` from `people` WHERE `name`='Fred' OR `name`='Susan'";
]]></programlisting>
                <para> En esta sintáxis es preferible escapar apóstrofes, ya que
                    es mucho más fácil de leer. </para>
            </sect3>

            <sect3
                id="coding-standard.coding-style.strings.variable-substitution">
                <title>Sustitución de Variables</title>

                <para> La sustitución de variables está permitida en cualquiera
                    de estas formas: </para>

                <programlisting language="php"><![CDATA[
$greeting = "Hello $name, welcome back!";

$greeting = "Hello {$name}, welcome back!";
]]></programlisting>

                <para> Por consistencia, esta forma no está permitida: </para>
                <programlisting language="php"><![CDATA[
$greeting = "Hello ${name}, welcome back!";
]]></programlisting>

            </sect3>

            <sect3
                id="coding-standard.coding-style.strings.string-concatenation">
                <title>Concatenación de cadenas</title>

                <para> Las cadenas deben ser concatenadas usando el operador
                    punto ("."). Un espacio debe añadirse siempre antes y
                    después del operador "." para mejorar la legibilidad: </para>
                <programlisting language="php"><![CDATA[
$company = 'Zend' . ' ' . 'Technologies';
]]></programlisting>

                <para> Al concatenar cadenas con el operador ".", se recomienda
                    partir la sentencia en múltiples líneas para mejorar la
                    legibilidad. En estos casos, cada linea sucesiva debe llevar
                    un margen de espacios en blanco de forma que el operador "."
                    está alineado bajo el operador "=": </para>
                <programlisting language="php"><![CDATA[
$sql = "SELECT `id`, `name` FROM `people` "
     . "WHERE `name` = 'Susan' "
     . "ORDER BY `name` ASC ";
]]></programlisting>
            </sect3>
        </sect2>

        <sect2 id="coding-standard.coding-style.arrays">
            <title>Arrays</title>

            <sect3 id="coding-standard.coding-style.arrays.numerically-indexed">
                <title>Arrays Indexados Numéricamente</title>

                <para>No están permitidos números negativos como índices.</para>

                <para> Un array indexado puede empezar por cualquier valor no
                    negativo, sin embargo, no se recomiendan índices base
                    distintos a 0. </para>

                <para> Al declarar arrays indexados con la función
                        <methodname>array</methodname> , un espacio de
                    separación deben añadirse después de cada coma, para mejorar
                    la legibilidad: </para>
                <programlisting language="php"><![CDATA[
$sampleArray = array(1, 2, 3, 'Zend', 'Studio');
]]></programlisting>

                <para> Se permite declarar arrays indexados multilínea usando la
                    construcción "array". En este caso, cada línea sucesiva debe
                    ser tabulada con cuatro espacios de forma que el principio
                    de cada línea está alineado: </para>
                <programlisting language="php"><![CDATA[
$sampleArray = array(1, 2, 3, 'Zend', 'Studio',
                     $a, $b, $c,
                     56.44, $d, 500);
]]></programlisting>

                <para> Alternativamente, el elemento inicial del array puede
                    comenzar en la siguiente línea. Si es así, debe ser alineado
                    en un nivel de sangría superior a la línea que contiene la
                    declaración del array, y todas las sucesivas líneas deben
                    tener la mismo indentación, el paréntesis de cierre debe ser
                    en una nueva línea al mismo nivel de indentación que la
                    línea que contiene la declaración del array: </para>

                <programlisting language="php"><![CDATA[
$sampleArray = array(
    1, 2, 3, 'Zend', 'Studio',
    $a, $b, $c,
    56.44, $d, 500,
);
]]></programlisting>

                <para> Al utilizar esta última declaración, recomendamos la
                    utilización de una coma detrás de el último elemento de la
                    matriz, lo que minimizará el impacto de añadir nuevos
                    elementos en las siguientes líneas, y ayuda a garantizar que
                    no se produzcan errores debido a la falta de una coma.
                </para>
            </sect3>

            <sect3 id="coding-standard.coding-style.arrays.associative">
                <title>Arrays Asociativos</title>

                <para> Al declarar arrays asociativos con la construcción
                        <methodname>array</methodname> , se recomienda partir la
                    declaración en múltiples líneas. En este caso, cada línea
                    sucesiva debe ser tabuladas con cuatro espacios de forma que
                    tanto las llaves como los valores están alineados: </para>

                <programlisting language="php"><![CDATA[
$sampleArray = array('firstKey'  => 'firstValue',
                     'secondKey' => 'secondValue');
]]></programlisting>

                <para> Alternativamente, el elemento inicial del array puede
                    comenzar en la siguiente línea. Si es así, debe ser alineado
                    en un nivel de sangría superior a la línea que contiene la
                    declaración del array, y todas las sucesivas líneas deben
                    tener la mismo indentación, el paréntesis de cierre debe ser
                    en una nueva línea al mismo nivel de indentación que la
                    línea que contiene la declaración del array: Para mejor
                    legibilidad, los diversos operadores de asiganción "=>"
                    deben ser rellenados con espacios en blanco hasta que se
                    alinien. </para>

                <programlisting language="php"><![CDATA[
$sampleArray = array(
    'firstKey'  => 'firstValue',
    'secondKey' => 'secondValue',
);
]]></programlisting>

                <para> Al utilizar esta última declaración, recomendamos la
                    utilización de una coma detrás de el último elemento de la
                    matriz, lo que minimizará el impacto de añadir nuevos
                    elementos en las siguientes líneas, y ayuda a garantizar que
                    no se produzcan errores debido a la falta de una coma. </para>

            </sect3>
        </sect2>

        <sect2 id="coding-standard.coding-style.classes">
            <title>Clases</title>

            <sect3 id="coding-standard.coding-style.classes.declaration">
                <title>Declaración de clases</title>

                <para> Las Clases deben ser nombradas de acuerdo a las
                    convencion de nombres de Zend Framework. </para>
                <para> La llave "{" deberá escribirse siempre en la línea debajo
                    del nombre de la clase ("one true brace"). </para>
                <para> Cada clase debe contener un bloque de documentación
                    acorde con el estándar de PHPDocumentor. </para>
                <para> Todo el código contenido en una clase debe ser separado
                    con cuatro espacios. </para>
                <para> Únicamente una clase está permitida por archivo
                        <acronym>PHP</acronym> . </para>
                <para> Incluir código adicional en archivos de clase está
                    permitido pero esta desaconsejado. En archivos de ese tipo,
                    dos líneas en blanco deben separar la clase de cualquier
                    código <acronym>PHP</acronym> adicional en el archivo de
                    clase. </para>
                <para> A continuación se muestra un ejemplo de una declaración
                    de clase que es permitida: </para>
                <programlisting language="php"><![CDATA[
/**
 * Bloque de Documentación aquí
 */
class SampleClass
{
    // el contenido de la clase
    // debe separarse con cuatro espacios
}
]]></programlisting>

                <para> Las clases que extiendan otras clases o interfaces
                    deberían declarar sus dependencias en la misma línea siempre
                    que sea posible. </para>

                <programlisting language="php"><![CDATA[
class SampleClass extends FooAbstract implements BarInterface
{
}
]]></programlisting>

                <para> Si como resultado de esas declaraciones, la longitud de
                    la línea excede la longitud del <link
                        linkend="coding-standard.php-file-formatting.max-line-length"
                        >Tamaño máximo de línea</link> , se debe romper la línea
                    antes de la palabra clave "extends" y / o "implements" e
                    indentarlo con un nivel de indentación (4 espacios). </para>

                <programlisting language="php"><![CDATA[
class SampleClass
    extends FooAbstract
    implements BarInterface
{
}
]]></programlisting>

                <para> If the class implements multiple interfaces and the
                    declaration exceeds the maximum line length, break after
                    each comma separating the interfaces, and indent the
                    interface names such that they align. </para>

                <programlisting language="php"><![CDATA[
class SampleClass
    implements BarInterface,
               BazInterface
{
}
]]></programlisting>
            </sect3>

            <sect3 id="coding-standard.coding-style.classes.member-variables">
                <title>Variables de miembros de clase</title>

                <para> Las variables de miembros de clase deben ser nombradas de
                    acuerdo con las conveciones de nombrado de variables de Zend
                    Framework. </para>
                <para> Cualquier variable declarada en una clase debe ser
                    listada en la parte superior de la clase, por encima de las
                    declaraciones de cualquier método. </para>
                <para> La construcción <emphasis>var</emphasis> no está
                    permitido. Las variables de miembro siempre declaran su
                    visibilidad usando uno los modificadores
                        <property>private</property> ,
                        <property>protected</property> , o
                        <property>public</property>. Dar acceso a las variables
                    de miembro declarándolas directamente como public está
                    permitido pero no se aconseja en favor de accesor methods
                    (set &amp; get). </para>
            </sect3>
        </sect2>

        <sect2 id="coding-standard.coding-style.functions-and-methods">
            <title>Funciones y Métodos</title>

            <sect3
                id="coding-standard.coding-style.functions-and-methods.declaration">
                <title>Declaración de Funciones y Métodos</title>

                <para> Las Funciones deben ser nombradas de acuerdo a las
                    convenciones de nombrado de Zend Framework. </para>
                <para> Los métodos dentro de clases deben declarar siempre su
                    visibilidad usando un modificador
                        <property>private</property> ,
                        <property>protected</property> , o
                        <property>public</property> . </para>
                <para> Como en las clases, la llave "{" debe ser escrita en la
                    línea siguiente al nombre de la función ("one true brace"
                    form). No está permitido un espacio entre el nombre de la
                    función y el paróntesis de apertura para los argumentos. </para>
                <para> Las funciones de alcance global no están permitidas. </para>
                <para> Lo siguiente es un ejemplo de una declaración admisible
                    de una función en una clase: </para>

                <programlisting language="php"><![CDATA[
/**
 * Bloque de Documentación aquí
 */
class Foo
{
    /**
     * Bloque de Documentación aquí
     */
    public function bar()
    {
        // el contenido de la función
        // debe separarse con cuatro espacios
    }
}
]]></programlisting>

                <para> In cases where the argument list exceeds the <link
                        linkend="coding-standard.php-file-formatting.max-line-length"
                        >maximum line length</link> , you may introduce line
                    breaks. Additional arguments to the function or method must
                    be indented one additional level beyond the function or
                    method declaration. A line break should then occur before
                    the closing argument paren, which should then be placed on
                    the same line as the opening brace of the function or method
                    with one space separating the two, and at the same
                    indentation level as the function or method declaration. The
                    following is an example of one such situation: </para>
                <programlisting language="php"><![CDATA[
/**
 * Documentation Block Here
 */
class Foo
{
    /**
     * Documentation Block Here
     */
    public function bar($arg1, $arg2, $arg3,
        $arg4, $arg5, $arg6
    ) {
        // all contents of function
        // must be indented four spaces
    }
}
]]></programlisting>

                <note>
                    <para>
                        <emphasis>NOTA:</emphasis> El paso por referencia es el
                        único mecanismo de paso de parámetros permitido en una
                        declaración de método. </para>
                </note>

                <programlisting language="php"><![CDATA[
/**
 * Bloque de Documentación aquí
 */
class Foo
{
    /**
     * Bloque de Documentación aquí
     */
    public function bar(&$baz)
    {}
}
]]></programlisting>

                <para> La llamada por referencia está estrictamente prohibida. </para>

                <para> El valor de retorno no debe estar indicado entre
                    paréntesis. Esto podría afectar a la legibilidad, además de
                    romper el código si un método se modifica posteriormente
                    para que devuelva por referencia. </para>
                <programlisting language="php"><![CDATA[
/**
 * Bloque de Documentación aquí
 */
class Foo
{
    /**
     * INCORRECTO
     */
    public function bar()
    {
        return($this->bar);
    }

    /**
     * CORRECTO
     */
    public function bar()
    {
        return $this->bar;
    }
}
]]></programlisting>

            </sect3>

            <sect3 id="coding-standard.coding-style.functions-and-methods.usage">
                <title>Uso de Funciones y Métodos</title>

                <para> Los argumentos de la función tendrían que estar separados
                    por un único espacio posterior después del delimitador coma.
                    A continuación se muestra un ejemplo de una invocación
                    admisible de una función que recibe tres argumentos: </para>

                <programlisting language="php"><![CDATA[
threeArguments(1, 2, 3);
]]></programlisting>

                <para> La llamada por referencia está estrictamente prohibida.
                    Vea la sección de declaraciones de funciones para el método
                    correcto de pasar argumentos por referencia. </para>
                <para> Al pasar arrays como argumentos a una función, la llamada
                    a la función puede incluir el indicador "hint" y puede
                    separarse en múltiples líneas para aumentar la legibilidad.
                    En esos casos, se aplican las pautas normales para escribir
                    arrays: </para>

                <programlisting language="php"><![CDATA[
threeArguments(array(1, 2, 3), 2, 3);

threeArguments(array(1, 2, 3, 'Zend', 'Studio',
                     $a, $b, $c,
                     56.44, $d, 500), 2, 3);

threeArguments(array(
    1, 2, 3, 'Zend', 'Studio',
    $a, $b, $c,
    56.44, $d, 500
), 2, 3);
]]></programlisting>

            </sect3>
        </sect2>

        <sect2 id="coding-standard.coding-style.control-statements">
            <title>Sentencias de Control</title>

            <sect3
                id="coding-standard.coding-style.control-statements.if-else-elseif">
                <title>If/Else/Elseif</title>

                <para> Las sentencias de control basadas en las construcciones
                        <emphasis>if</emphasis> y <emphasis>elseif</emphasis>
                    deben tener un solo espacio en blanco antes del paréntesis
                    de apertura del condicional y un solo espacio en blanco
                    después del paréntesis de cierre. </para>

                <para> Dentro de las sentencias condicionales entre paréntesis,
                    los operadores deben separarse con espacios, por
                    legibilidad. Se aconseja el uso de paréntesis internos para
                    mejorar la agrupación lógica en expresiones condicionales
                    más largas. </para>

                <para> La llave de apertura "{" se escribe en la misma línea que
                    la sentencia condicional. La llave de cierre "}" se escribe
                    siempre en su propia línea. Cualquier contenido dentro de
                    las llaves debe separarse con cuatro espacios en blanco. </para>
                <programlisting language="php"><![CDATA[
if ($a != 2) {
    $a = 2;
}
]]></programlisting>

                <para> If the conditional statement causes the line length to
                    exceed the <link
                        linkend="coding-standard.php-file-formatting.max-line-length"
                        >maximum line length</link> and has several clauses, you
                    may break the conditional into multiple lines. In such a
                    case, break the line prior to a logic operator, and pad the
                    line such that it aligns under the first character of the
                    conditional clause. The closing paren in the conditional
                    will then be placed on a line with the opening brace, with
                    one space separating the two, at an indentation level
                    equivalent to the opening control statement. </para>

                <programlisting language="php"><![CDATA[
if (($a == $b)
    && ($b == $c)
    || (Foo::CONST == $d)
) {
    $a = $d;
}
]]></programlisting>

                <para> The intention of this latter declaration format is to
                    prevent issues when adding or removing clauses from the
                    conditional during later revisions. </para>

                <para> Para las declaraciones "if" que incluyan "elseif" o
                    "else", las convenciones de formato son similares a la
                    construcción "if". Los ejemplos siguientes demuestran el
                    formato correcto para declaraciones "if" con construcciones
                    "else" y/o "elseif": </para>

                <programlisting language="php"><![CDATA[
if ($a != 2) {
    $a = 2;
} else {
    $a = 7;
}

if ($a != 2) {
    $a = 2;
} elseif ($a == 3) {
    $a = 4;
} else {
    $a = 7;
}

if (($a == $b)
    && ($b == $c)
    || (Foo::CONST == $d)
) {
    $a = $d;
} elseif (($a != $b)
          || ($b != $c)
) {
    $a = $c;
} else {
    $a = $b;
}
]]></programlisting>

                <para>
                    <acronym>PHP</acronym> permite escribir sentencias sin
                    llaves -{}- en algunas circunstancias. Este estándar de
                    código no hace ninguna diferenciación- toda sentencia "if",
                    "elseif" o "else" debe usar llaves. </para>

                <para> El uso de la construcción "elseif" está permitido pero no
                    se aconseja, en favor de la combinación "else if". </para>
            </sect3>

            <sect3 id="coding-standards.coding-style.control-statements.switch">
                <title>Switch</title>

                <para> Las declaraciones de control escritas con la declaración
                    "switch" deben tener un único espacio en blanco antes del
                    paréntesis de apertura del condicional y después del
                    paréntesis de cierre. </para>

                <para> Todo contenido dentro de una declaración "switch" debe
                    separarse usando cuatro espacios. El contenido dentro de
                    cada declaración "case" debe separarse usando cuatro
                    espacios adicionales. </para>

                <programlisting language="php"><![CDATA[
switch ($numPeople) {
    case 1:
        break;

    case 2:
        break;

    default:
        break;
}
]]></programlisting>

                <para> La construcción <property>default</property> no debe
                    omitirse nunca en una declaración
                        <property>switch</property> . </para>

                <note>
                    <para>
                        <emphasis>NOTA:</emphasis> En ocasiones, resulta útil
                        escribir una declaración <property>case</property> que
                        salta al siguiente case al no incluir un
                            <property>break</property> o
                            <property>return</property> dentro de ese case. Para
                        distinguir estos casos de posibles errores, cualquier
                        declaración donde <property>break</property> o
                            <property>return</property> sean omitidos deberán
                        contener un comentario indicando que se omitieron
                        intencionadamente. </para>
                </note>
            </sect3>
        </sect2>

        <sect2 id="coding-standards.inline-documentation">
            <title>Documentación integrada</title>

            <sect3
                id="coding-standards.inline-documentation.documentation-format">
                <title>Formato de documentación</title>

                <para> Todos los bloques de documentación ("docblocks") deben
                    ser compatibles con el formato de phpDocumentor. Describir
                    el formato de phpDocumentor está fuera del alcance de este
                    documento. Para más información, visite: <ulink
                        url="http://phpdoc.org/">http://phpdoc.org/</ulink>
                </para>

                <para> Todos los archivos de clase deben contener un bloque de
                    documentación "a nivel de archivo" al principio de cada
                    archivo y un bloque de documentación "a nivel de clase"
                    inmediatamente antes de cada clase. Ejemplo de estos bloques
                    de documentación pueden encontrarse debajo. </para>
            </sect3>

            <sect3 id="coding-standards.inline-documentation.files">
                <title>Archivos</title>

                <para> Cada archivo que contenga código <acronym>PHP</acronym>
                    debe tener un bloque de documentación al principio del
                    archivo que contenga como mínimo las siguientes etiquetas
                    phpDocumentor: </para>

                <programlisting language="php"><![CDATA[
/**
 * Descripción corta del fichero
 *
 * Descripción larga del fichero (si la hubiera)...
 *
 * LICENSE: Some license information
 *
 * @category   Zend
 * @package    Zend_Magic
 * @subpackage Wand
 * @copyright  Copyright (c) 2005-2015 Zend Technologies USA Inc. (http://www.zend.com)
 * @license    http://framework.zend.com/license   BSD License
 * @version    $Id:$
 * @link       http://framework.zend.com/package/PackageName
 * @since      File available since Release 1.5.0
*/
]]></programlisting>

                <para> The <property>@category</property> annotation must have a
                    value of "Zend". </para>

                <para> The <property>@package</property> annotation must be
                    assigned, and should be equivalent to the component name of
                    the class contained in the file; typically, this will only
                    have two segments, the "Zend" prefix, and the component
                    name. </para>

                <para> The <property>@subpackage</property> annotation is
                    optional. If provided, it should be the subcomponent name,
                    minus the class prefix. In the example above, the assumption
                    is that the class in the file is either "
                        <classname>Zend_Magic_Wand</classname> ", or uses that
                    classname as part of its prefix. </para>

            </sect3>

            <sect3 id="coding-standards.inline-documentation.classes">
                <title>Clases</title>

                <para> Cada clase debe contener un bloque de documentación que
                    contenga como mínimo las siguientes etiquetas phpDocumentor: </para>
                <programlisting language="php"><![CDATA[
/**
 * Descripción corta de la clase
 *
 * Descripcion larga de la clase (si la hubiera)...
 *
 * @category   Zend
 * @package    Zend_Magic
 * @subpackage Wand
 * @copyright  Copyright (c) 2005-2015 Zend Technologies USA Inc. (http://www.zend.com)
 * @license    http://framework.zend.com/license   BSD License
 * @version    Release: @package_version@
 * @link       http://framework.zend.com/package/PackageName
 * @since      Class available since Release 1.5.0
 * @deprecated Class deprecated in Release 2.0.0
 */
]]></programlisting>

                <para> The <property>@category</property> annotation must have a
                    value of "Zend". </para>

                <para> The <property>@package</property> annotation must be
                    assigned, and should be equivalent to the component to which
                    the class belongs; typically, this will only have two
                    segments, the "Zend" prefix, and the component name. </para>

                <para> The <property>@subpackage</property> annotation is
                    optional. If provided, it should be the subcomponent name,
                    minus the class prefix. In the example above, the assumption
                    is that the class described is either "
                        <classname>Zend_Magic_Wand</classname> ", or uses that
                    classname as part of its prefix. </para>

            </sect3>

            <sect3 id="coding-standards.inline-documentation.functions">
                <title>Funciones</title>

                <para> Cada función, incluyendo métodos de objeto, debe contener
                    un bloque de documentación que contenga como mínimo: </para>

                <itemizedlist>
                    <listitem>
                        <para>Una descripción de la función</para>
                    </listitem>
                    <listitem>
                        <para>Todos los argumentos</para>
                    </listitem>
                    <listitem>
                        <para>Todos los posibles valores de retorno</para>
                    </listitem>
                </itemizedlist>

                <para> No es necesario incluir la etiqueta "@access" si el nivel
                    de acceso es conocido de antemano por el modificador
                    "public", "private", o "protected" usado para declarar la
                    función. </para>

                <para> Si una función/método puede lanzar una excepción, utilice
                    @throws para todos los tipos de excepciones conocidas: </para>

                <programlisting language="php"><![CDATA[
@throws exceptionclass [description]
]]></programlisting>
            </sect3>
        </sect2>
    </sect1>

</appendix>