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

<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 18940 -->
<!-- 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:

                    <programlisting language="php"><![CDATA[
$greeting = "Hello ${name}, welcome back!";
]]></programlisting>
                </para>
            </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  2008 Zend Technologies
 * @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  2008 Zend Technologies
 * @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>
<!--
vim:se ts=4 sw=4 et:
-->