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 licencia Temas incluídos en los estándares de código ZF: Dar formato a archivos PHP Convenciones de nombrado Estilo de código Documentación integrada 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 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. IMPORTANTE: La inclusión de datos binarios arbitrarios permitidos por __HALT_COMPILER() 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. La identación suele estar compuesta por 4 espacios. Las tabulaciones no están permitidas. 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. 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. 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). 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. 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"). 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. 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. Vea los nombres de clase en las bibliotecas estandar y adicionales (extras) como ejemplos de esta convención de nombres. IMPORTANTE: 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 cualquier otro archivo, sólo caracteres alfanuméricos, barras bajas (_) y guiones (-) están permitidos. Los espacios en blanco están estrictamente prohibidos. 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..: Los nombres de archivo deben apuntar a nombres de clases como se describe arriba. 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. 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". 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. Estos son ejemplos de nombres de funciones admisibles: 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 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. 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. 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 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. 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". 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. Las constantes pueden contener tanto caracteres alfanuméricos como barras bajas (_). Los números están permitidos. Todos las letras pertenecientes al nombre de una constante deben aparecer en mayúsculas. Las palabras dentro del nombre de una constante deben separarse por barras bajas (_). Por ejemplo, EMBED_SUPPRESS_EMBED_EXCEPTION está permitido, pero EMBED_SUPPRESSEMBEDEXCEPTION no. 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. El código PHP debe estar delimitado siempre por la forma completa de las etiquetas PHP estándar: ]]> 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 ). 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: Cuando el propio literal cadena contega apóstrofos, es permitido delimitar la cadena con "dobles comillas". Esto es especialmente útil para sentencias SQL: Esta sintáxis es preferible a escapar apóstrofes, ya que es mucho más fácil de leer. La sustitución de variables está permitida en cualquiera de estas formas: Por consistencia, esta forma no está permitida: 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: 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 "=": No están permitidos números negativos como índices. Un array indexado puede empezar por cualquier valor no negativo, sin embargo, no se recomiendan índices base distintos a 0. Al declarar arrays indexados con la función array, un espacio de separación deben añadirse después de cada delimitador coma para mejorar la legibilidad: 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: Al declarar arrays asociativos con la construcción array, 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: 'firstValue', 'secondKey' => 'secondValue'); ]]> Las Clases deben ser nombradas de acuerdo a las convenciones de nombrado de Zend Framework. La llave "{" deberá escribirse siempre en la línea debajo del nombre de la clase ("one true brace"). Cada clase debe contener un bloque de documentación acorde con el estándar de PHPDocumentor. Todo el código contenido en una clase debe ser separado con cuatro espacios. Únicamente una clase está permitida en cada archivo PHP. 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. A continuación se muestra un ejemplo de una declaración de clase admisible: Las variables de miembros de clase deben ser nombradas de acuerdo con las conveciones de nombrado de variables de Zend Framework. 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. La construcción var no está permitido. Las variables de miembro siempre declaran su visibilidad usando uno los modificadores private, protected, o public. 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). Las Funciones deben ser nombradas de acuerdo a las convenciones de nombrado de Zend Framework. Los métodos dentro de clases deben declarar siempre su visibilidad usando un modificador private, protected, o public. 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. Las funciones de alcance global no están permitidas. Lo siguiente es un ejemplo de una declaración admisible de una función en una clase: NOTA: El paso por referencia es el único mecanismo de paso de parámetros permitido en una declaración de método. La llamada por referencia está estrictamente prohibida. 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. bar); } /** * CORRECTO */ public function bar() { return $this->bar; } } ]]> 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: 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. 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: Las sentencias de control basadas en las construcciones if y elseif 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. 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. 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 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": 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. El uso de la construcción "elseif" está permitido pero no se aconseja, en favor de la combinación "else if". 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. 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. La construcción default no debe omitirse nunca en una declaración switch. NOTA: En ocasiones, resulta útil escribir una declaración case que salta al siguiente case al no incluir un break o return dentro de ese case. Para distinguir estos casos de posibles errores, cualquier declaración donde break o return sean omitidos deberán contener un comentario indicando que se omitieron intencionadamente. 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: http://phpdoc.org/ 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. 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: Cada clase debe contener un bloque de documentación que contenga como mínimo las siguientes etiquetas phpDocumentor: Cada función, incluyendo métodos de objeto, debe contener un bloque de documentación que contenga como mínimo: Una descripción de la función Todos los argumentos Todos los posibles valores de retorno 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. Si una función/método puede lanzar una excepción, utilice @throws para todos los tipos de excepciones conocidas: