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

<?xml version="1.0" encoding="UTF-8"?>
<!-- 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.
                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ñoo.
                Estas pautas en los estándares de código de Zend Framework
                han demostrado funcionar bien en otros projectos ZF.
                Puede modificar estos estándares o usarlos en consonancia con
                los términos de nuestra <ulink url="http://framework.zend.com/license">licencia</ulink>
            </para>
            <para>
                Temas incluídos en los estándares de código ZF:
                <itemizedlist>
                    <listitem>
                        <para>Dar formato a archivos PHP</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>
            </para>
        </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 PHP,
                la etiqueta de cierre ("?>") no está permitida.
                No es requerida por PHP, y omitirla evita la inyección de
                espacios en blanco en la respuesta.
            </para>

            <para>
                <emphasis>IMPORTANTE:</emphasis> La inclusión de datos binarios
                arbitrarios permitidos por <code>__HALT_COMPILER()</code>
                está prohibida en los archivos PHP 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>
        </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 PHP 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 (CRLF) estandar para sistemas operativos
                Windows (0x0D, 0x0A).
            </para>
        </sect2>
    </sect1>

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

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

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

            <para>
                Los nombres de clase 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  "Zend/Db/Table.php" debe apuntar al nombre de
                clase "Zend_Db_Table").
            </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 "Zend_Pdf"
                es admisible.
            </para>

            <para>
                Estas convenciones definen un mecanismo de pseudo-espacio de
                nombres para Zend Framework. Zend Framework adoptará la
                funcionalidad PHP 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.
                <emphasis>IMPORTANTE:</emphasis> El código que deba distribuirse
                junto a las bibliotecas ZF, 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>
        </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 PHP debe terminar con la
                extensión ".php", con la excepción de los scripts de vista.
                Los siguientes ejemplos muestran nombres de archivo admisibles
                para clases de Zend Framework..:
                <programlisting role="php"><![CDATA[
Zend/Db.php

Zend/Controller/Front.php

Zend/View/Helper/FormRadio.php
]]>
                </programlisting>

                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:

                <programlisting role="php"><![CDATA[
filterInput()

getElementById()

widgetFactory()
]]>
                </programlisting>
            </para>

            <para>
                Para programación orientada a objetos, los accesores para
                instancia o variables estáticas deben ir antepuestos con un
                "get" o un "set". Al implementar patrones 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 métodos en objetos que 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 "$i" y "$n" 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,
                <code>EMBED_SUPPRESS_EMBED_EXCEPTION</code> está permitido, pero
                <code>EMBED_SUPPRESSEMBEDEXCEPTION</code> 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 PHP debe estar delimitado siempre por la forma
                completa de las etiquetas PHP estándar:

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

?>
]]>
                </programlisting>
            </para>

            <para>
                Las etiquetas cortas (short tags) no se permiten nunca.
                Para archivos que contengan únicamente código PHP, 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</title>

            <sect3 id="coding-standard.coding-style.strings.literals">
                <title>Literales cadena</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:

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

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

                <para>
                    Cuando el propio literal cadena contega apóstrofos,
                    es permitido delimitar la cadena	con "dobles comillas".
                    Esto es especialmente útil para sentencias SQL:

                    <programlisting role="php"><![CDATA[
$sql = "SELECT `id`, `name` from `people` WHERE `name`='Fred' OR `name`='Susan'";
]]>
                    </programlisting>

                    Esta sintáxis es preferible a 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:

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

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

                <para>
                    Por consistencia, esta forma no está permitida:

                    <programlisting role="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:

                    <programlisting role="php"><![CDATA[
$company = 'Zend' . ' ' . 'Technologies';
]]>
                    </programlisting>
                </para>

                <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 "=":

                    <programlisting role="php"><![CDATA[
$sql = "SELECT `id`, `name` FROM `people` "
     . "WHERE `name` = 'Susan' "
     . "ORDER BY `name` ASC ";
]]>
                    </programlisting>
                </para>
            </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
                    <code>array</code>, un espacio de separación deben
                    añadirse después de cada delimitador coma para mejorar la
                    legibilidad:

                    <programlisting role="php"><![CDATA[
$sampleArray = array(1, 2, 3, 'Zend', 'Studio');
]]>
                    </programlisting>
                </para>

                <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:

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

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

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

                    <programlisting role="php"><![CDATA[
$sampleArray = array('firstKey'  => 'firstValue',
                     'secondKey' => 'secondValue');
]]>
                    </programlisting>
                </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
                    convenciones de nombrado 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 en cada archivo PHP.
                </para><para>
                    Incluir código adicional en archivos de clase está
                    permitido pero desaconsejado.
                    En archivos de ese tipo, dos líneas en blanco deben
                    separar la clase de cualquier código PHP adicional en el
                    archivo de clase.
                </para><para>
                    A continuación se muestra un ejemplo de una declaración de
                    clase admisible:

                    <programlisting role="php"><![CDATA[
/**
 * Bloque de Documentación aquí
 */
class SampleClass
{
    // el contenido de la clase
    // debe separarse con cuatro espacios
}
]]>
                    </programlisting>
                </para>
            </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 <code>var</code> no está permitido.
                    Las variables de miembro siempre declaran su visibilidad
                    usando uno los modificadores <code>private</code>,
                    <code>protected</code>, o <code>public</code>.
                    Dar acceso a las variables de miembro declarándolas
                    directamente como public está permitido pero no se aconseja
                    en favor de accesor methods (set/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 <code>private</code>,
                    <code>protected</code>, o <code>public</code>.
                </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:

                    <programlisting role="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>

                <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.

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

                <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.

                    <programlisting role="php"><![CDATA[
/**
 * Bloque de Documentación aquí
 */
class Foo
{
    /**
     * INCORRECTO
     */
    public function bar()
    {
        return($this->bar);
    }

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

            </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:

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

                <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:

                    <programlisting role="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);
]]>
                    </programlisting>
                </para>
            </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
                    <code>if</code> y <code>elseif</code> 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.

                    <programlisting role="php"><![CDATA[
if ($a != 2) {
    $a = 2;
}
]]>
                    </programlisting>
                </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":

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

if ($a != 2) {
    $a = 2;
} elseif ($a == 3) {
   $a = 4;
} else {
   $a = 7;
}
]]>
                    </programlisting>
                    PHP 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 role="php"><![CDATA[
switch ($numPeople) {
    case 1:
        break;

    case 2:
        break;

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

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

                <para>
                    <emphasis>NOTA:</emphasis> En ocasiones, resulta útil
                    escribir una declaración <code>case</code> que salta al	
                    siguiente case al no incluir un <code>break</code> o
                    <code>return</code> dentro de ese case. Para distinguir	
                    estos casos de posibles errores, cualquier declaración
                    donde <code>break</code> o <code>return</code> sean	
                    omitidos deberán contener un comentario indicando que se
                    omitieron intencionadamente.
                </para>
            </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>Archivo</title>

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

                    <programlisting role="php"><![CDATA[
/**
 * Descripción corta del fichero
 *
 * Descripción larga del fichero (si la hubiera)...
 *
 * LICENSE: Información sobre la licencia
 *
 * @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>
            </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:

                    <programlisting role="php"><![CDATA[
/**
 * Descripción corta de la clase
 *
 * Descripcion larga de la clase (si la hubiera)...
 *
 * @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>
            </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:

                    <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>

                <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:

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

</appendix>
<!--
vim:se ts=4 sw=4 et:
-->