Estndares de codificacin de sistemas - 18/10/06 12:09:10

Estndares de codificacin de sistemas

(Revisin 1)
La Direccin General de Gobierno Digital participa activamente a lo largo del ciclo de vida del desarrollo de un software para asegurar la calidad del mismo. Uno de los instrumentos que facilitan esta tarea es la adopcin de estndares de estilo y codificacin. El uso de estos estndares tiene innumerables ventajas, entre ellas:

Asegurar la legibilidad del cdigo entre distintos programadores, facilitando el debugging del mismo,

Proveer una gua para el encargado de mantenimiento/actualizacin del sistema, con cdigo claro y bien documentado,

Facilitar la portabilidad entre plataformas y aplicaciones.

Es por esto que la codificacin de los mdulos del Sistema a desarrollar debe cumplir ciertos requisitos, detallados en el presente documento. Estos requisitos estn basados en el estndar de la comunidad PEAR (http://pear.php.net/manual/en/standards.php). Pueden aplicarse a cualquier lenguaje de programacin, exceptuando algunas reglas especficas correspondientes a PHP. Cabe destacar que, en casos particulares, cualquier item expresado en el presente documento puede ser sujeto a consideracin, por ejemplo, al utilizar un framework de desarrollo que necesite / implemente una nomenclatura especfica. Para ello, el desarrollador deber proveer a esta Direccin General la documentacin correspondiente a tal caso (por ejemplo, la documentacin del framework). Los estndares se resumen en los siguientes puntos:

1. Variables locales

Los nombres de algunas variables locales, como los iteradores o los contadores, pueden especificarse en minscula y de forma abreviada, siempre que su contexto sea especficamente local y su lectura sea intuitiva. Ejemplos: $cont, $i, $j.

Al hacer asignaciones, debe existir un espacio a ambos lados del signo igual

Estndares de codificacin de sistemas - 18/10/06 12:09:10 (=), esto funciona tanto para asignar un valor fijo, de otra variable o del resultado de una funcin.

En el caso de un bloque de asignaciones relacionadas entre s (por ejemplo, al inicializar un script), se pueden alinear los signos (=) agregando espacios extra, para mejorar la legibilidad.

2. Indentacin y largo de lneas

Indentar con 4 espacios, sin tabulador, para que cualquier editor de texto reconozca correctamente la indentacin. Por otro lado, si bien existen editores que realizan corte automtico de lnea, es recomendable hacerlo en forma manual a los 75-80 caracteres.

3. Estructuras de control

Incluye if, for, while, switch, etc. Deben tener un espacio entre la palabra clave y el parntesis de apertura, para diferenciarlos de las llamadas a funciones. Se recomienda encarecidamente, aunque no sea necesario, la utilizacin de llaves. Esto mejora la legibilidad y disminuye la posibilidad de errores lgicos al agregar nuevas lneas de cdigo.

4. Llamadas a funciones

Las funciones deben ser llamadas sin espacio entre el nombre de la funcin, el parntesis de apertura y el primer parmetro. En caso de varios parmetros, separar con espacios entre la coma y cada parmetro, y sin espacios entre el ltimo parmetro, el parntesis de cierre y el punto y coma.

5. Definicin de funciones

Las

definiciones

de

funciones

utilizan

el

estilo

BSD/Allman.

Las

caractersticas ms importantes se resaltan a continuacin:

El nombre debe ser lo ms descriptivo posible, Se debe evitar el uso de abreviaturas, Se debe utilizar la convencin lowerCamelCase. Para ms informacin, (http://en.wikipedia.org/wiki/CamelCase).

Colocar los argumentos con valores por defecto, al final de la lista.

Estndares de codificacin de sistemas - 18/10/06 12:09:10 Siempre intentar retornar un valor significativo. La llave de inicio de la funcin se coloca en la lnea siguiente, indentada correctamente.

6. Definicin de clases

El nombre debe ser descriptivo, evitando abreviaturas, usando la convencin UpperCamelCase (http://en.wikipedia.org/wiki/CamelCase).

La llave de inicio de la clase se coloca en la lnea siguiente, indentada correctamente.

Todos los miembros de la clase deben ser privados, es decir, nicamente accesibles a travs de mtodos de la misma.

Si el framework de desarrollo especifica convenciones de nombres de clases/mtodos/propiedades, respetarlas.

7. Comentarios

Se aconseja el uso de comentarios en lnea para facilitar la comprensin del cdigo, sobre todo en procedimientos complejos. Los comentarios pueden ser con fin documental o bien como 'ayuda-memoria'.

Se recomienda utilizar los estilos de C (/* */) y C++ (// ), no tanto as el signo numeral o sharp (#).

8. Inclusin de cdigo

Salvo casos especficos y puntuales, utilizar require_once para incluir cdigo incondicionalmente, e include_once para los casos condicionales (o sus equivalentes en otros lenguajes).

9. Etiquetas de bloque PHP

Siempre utilizar <?php y ?> para iniciar y terminar un bloque de cdigo PHP, no las variantes <? y ?> o <% y %>. Esto asegura compatibilidad entre diversas configuraciones de equipos.

10. URLs de ejemplo

Estndares de codificacin de sistemas - 18/10/06 12:09:10

Para denotar URLs de ejemplo y direcciones de e-mail en la documentacin y comentarios, utilizar las especificadas stas pueden en ser: la RFC2606 (http://www.faqs.org/rfcs/rfc2606). example.org, example.net. example.com,

11. Variables globales (Constantes)

Los nombres de variables globales deben ser siempre en MAYSCULAS, separando las palabras con guiones bajos (_).

Existen tres excepciones al punto anterior, las cuales deben escribirse siempre en minscula: true, false y null.