Normas de estilo para la codificación de programas v.1.0

11/09/97 12.17

Departamento de Informática e Ingeniería de Sistemas Centro Politécnico Superior Universidad de Zaragoza María de Luna 3 50015, Zaragoza

Normas de estilo para la codificación de programas

1 de 7

1. INTRODUCCIÓN ............................................................................................................................. 2

2. CABECERA DEL FICHERO/MÓDULO ...................................................................................... 2

3. CONSTANTES Y VARIABLES GLOBALES Y TIPOS .............................................................. 2 3.1 CONSTANTES ................................................................................................................................. 2 3.2 VARIABLES .................................................................................................................................... 2 3.3 TIPOS ............................................................................................................................................. 3 4. FUNCIONES Y SERVICIOS........................................................................................................... 3 4.1 ENCABEZAMIENTO ....................................................................................................................... 3 4.2 PARÁMETROS ................................................................................................................................ 3 5. FLUJO DE CONTROL .................................................................................................................... 4 5.1 LA SENTENCIA IF ........................................................................................................................... 4 5.2 FLUJO DE CONTROL NO LINEAL ................................................................................................... 4 6. CUESTIONES LÉXICAS................................................................................................................. 4 6.1 CONVENCIONES DE NOMBRES ...................................................................................................... 4 6.2 INDENTACIÓN Y ESPACIOS EN BLANCO ....................................................................................... 5

Dep. de Informática e Ing. de Sistemas

estcod.doc

5/10/00

Normas de estilo para la codificación de programas

2 de 7

1. Introducción Estas normas son una guia de estilo para la codificación de programas. La experiencia ha demostrado que estas normas son beneficiosas para reducir errores semánticos y demandan cierta consistencia en la elección de nombres y la organización. Adicionalmente tienen por objeto asegurar la uniformidad de código entre los distintos programadores. Para esta guía se ha tomado como base las normas propuestas en [HORST95] que se han adaptado y ampliado a partir de gustos personales y experiencia de los autores.

2. Cabecera del fichero/módulo Cada módulo comienza por una cabecera de comentarios con el siguiente formato: /**************************************************************** COPYRIGHT(C): F.Javier Zarazaga PROYECTO: Practicas Proyectos 1997/98 ARCHIVO: /usr/zarazaga/metodologias/fichero1.h LENGUAJE: C++ standard PLATAFORMA: Si depende de alguna plataforma p.e. Unix/windows REQUERIM.: Si depende de librerias u otros requerimientos especiales (p.e: librerias graficas, de acceso a bases de datos, ..) DESCRIPCION: una pequegna descripcion del contenido del fichero ****************************************************************/

3. Constantes y variables globales y tipos 3.1 Constantes Las constantes, variables globales (al módulo) y tipos se encabezancon el siguiente formato: /* CONSTANTES Y VARIABLES GLOBALES Y TIPOS DEL MODULO ************ */

3.2 Variables Cada variable local, con la excepción de las que tienen nombres realmente autoexplicativos y los aburridos contadores de bucle, deben ser comentadas cuando se declaran. Todas las variables globales deben ser comentadas sin excepción. integer nfont; // Numero de fuentes cargados actualmente

Dep. de Informática e Ing. de Sistemas

estcod.doc

5/10/00

Normas de estilo para la codificación de programas

3 de 7

3.3 Tipos Se debe realizar la especificación algebraica de aquellos tipos que se definan por el programador.

4. Funciones y servicios 4.1 Encabezamiento Comienzan con el siguiente encabezamiento: /* FUNCIONES Y SERVICIOS **************************************** */ Comienzan con un encabezamiento con el siguiente formato: /* SERVICIO (o en su caso FUNCION) -----------------------------PROPOSITO: obligatorio a no ser que sea obvio RECIBE: argumento1 -- explicacion (en caso de haber algun argumento) argumento2 (OUT) -- explicacion (poner (OUT) en caso que sea de salida)(o (IN/OUT) en caso de entrada/salida) ... DEVUELVE: explicacion del valor devuelto (omitido para funciones que no devuelven nada) PRE/POST: pre y post condiciones, excepciones, observaciones, ... */ long nombreDeLaFuncion(int d, int m, int a) { ... }

El PROPOSITO es obligatorio excepto asignaciones, operaciones de acceso, y funciones muy triviales. Para main no se hacen comentarios de entradas y salidas.

4.2 Parámetros Los nombres de los parámetros deben ser explícitos, especialmente si son enteros y booleanos. void borrarCliente(int i, Bool b); Void borrarCliente(int numeroCliente, Bool conConfirmacion);

// NO! // OK

Por supuesto, para funciones muy genéricas, nombres cortos pueden ser muy apropiados. Si la función realiza algún tipo de operación que puede dar error el valor devuelto debe ser el código de error producido o 0 en caso satisfactorio. Los datos se devuelven a través de referencias. void buscarCliente(Cliente c, Bool& found); status buscarCliente(Cliente c);

Dep. de Informática e Ing. de Sistemas

estcod.doc

// NO! // OK

5/10/00

Normas de estilo para la codificación de programas

4 de 7

5. Flujo de Control 5.1 La sentencia if Evitar la trampa del ”if...if...else“ . El código if( ... ) then if( ... ) ...; else begin ...; ... end;

no hará lo que sugieren los niveles de indentación, y se pueden necesitar horas para encontrar el error. Utilizar siempre un par extra de begin . . . end cuando se trate de ”if...if...else“: if( ... ) then begin if( ... ) then ...; else( ... ) ...; end;

5.2 Flujo de control no lineal No utilizar las sentencias de continue, o goto bajo ninguna circunstancia. Siempre es posible evitarlas en un bucle añadiendo una variable booleana. Hace el bucle más claro, porque es más fácil verificar el invariante del bucle.

6. Cuestiones léxicas 6.1 Convenciones de nombres Las siguientes reglas especifican cuando utilizar letras mayúsculas o minúsculas en los identificadores. 1. Todos los nombres de variables y funciones y todos los miembros de estructuras van en minúsculas (pueden tener mayúsculas en el medio para identificar la separación de palabras dentro del identificador). 2. Todos los nombres de tipos, tipos abstractos de datos y clases deben empezar por mayuscula segido de minuscula (pueden tener mayúsculas en el medio para identificar la separación de palabras dentro del identificador). 3. Para el nombre se deben utilizar únicamente las letras de la ‘a’ a la ‘z’ y éste debe ser lo más clarificador posible.

Dep. de Informática e Ing. de Sistemas

estcod.doc

5/10/00

Normas de estilo para la codificación de programas

5 de 7

6.2 Indentación y espacios en blanco Utilizar tabuladores fijados a tamaño constante (por ejemplo cada 3 columnas). Utilizar líneas en blanco libremente para separar partes lógicas distintas de una función. Utilizar espacios en blanco alrededor de cada operador binario x := 3; x:=3;

// OK // NO!

Dejar espacios en blanco después (y no antes) de cada coma y punto y coma, pero no después de un nombre de función. f(a, b[i++]) ; f(a, b[i++]);

// NO! // OK

Todas las líneas deben encajar en 80 columnas. Si hay que romper una instrucción, añade un nivel de indentación para la continuación. a[n] := .............................................................. + ...............;

Si es posible comenzar la línea indentada con un operador. Sangrar continuamente los diferentes niveles de código: Correcto begin if(x = y) then begin z := 10; h := x end; . . . end

Incorrecto begin if(x = y) then begin z := 10; h := x end; . . . end

Dep. de Informática e Ing. de Sistemas

estcod.doc

5/10/00

Normas de estilo para la codificación de programas

6 de 7

REFERENCIAS [HORST95]

C. S. Horstmann. "Mastering Object-Oriented Design in C++". Whiley. 1995

[IAAA96]

F.J.Zarazaga, P.R.Muro, J.Valiño, “POOD/1 - Normas de estilo para la codificación de programas”. Documento interno del grupo IAAA.

Dep. de Informática e Ing. de Sistemas

estcod.doc

5/10/00