Guía de Estilo de PASCAL

GUÍA DE ESTILO DE PASCAL

Este documento tiene como finalidad proporcionar un conjunto de reglas que nos ayuden a escribir programas en Pascal con un "buen estilo". Un código escrito con buen estilo es aquel que tiene las siguientes propiedades:

• Está organizado.
• Es fácil de leer.
• Es fácil de mantener.
• Es fácil detectar errores en él.
• Es eficiente.

Hay muchos estilos que cumplen estas características. En este documento simplemente vamos a dar uno de ellos. Este documento es una versión resumida y adaptada de la guía de estilo para C de Juan José Moreno Moll (http://bugs/guia/asignatu/EDS/9697/ESTILO/estilo20.html)

Los principios de esta sección sirven para aumentar la legibilidad del código y para facilitar su mantenimiento. Éstos son:

• Organizar programas utilizando técnicas para encapsular y ocultar información.
• Aumentar la legibilidad usando los espacios y líneas en blanco.
• Añadir comentarios para ayudar a otras personas a entender el programa.
• Utilizar identificadores que ayuden a entender el programa.

La encapsulación y ocultación de información ayudan a organizar mejor el código y evitan el acoplamiento entre funciones del código.

La encapsulación permite agrupar elementos afines del programa. Los subprogramas afines se agrupan en ficheros (unidades), y los datos en grupos lógicos (estructuras de datos).

Ocultación de información: Un subprograma no necesita saber lo siguiente:

• La fuente de los parámetros que se le pasan como entrada.
• Para qué servirán sus salidas.
• Qué subprogramas se activaron antes que él.
• Qué subprogramas se activarán después que él.
• Cómo están implementados internamente otros subprogramas.

Para conseguir esto se deben seguir las siguientes reglas:

• No hacer referencia o modificar variables globales (evitar efectos laterales).
• Declarar las variables y tipos como locales a los subprogramas que los utilizan.
• Si queremos evitar cambios indeseados en parámetros, pasarlos por valor.
• Un procedimiento sólo debe modificar los parámetros pasados en su llamada.

Los comentarios dan información sobre lo que hace el código en el caso que no sea fácil comprenderlo con una lectura rápida. Se usan para añadir información o para aclarar secciones de código. No se usan para describir el programa. Por lo tanto no se deben poner comentarios a una sola instrucción. Los comentarios se añaden en los niveles siguientes:

• Comentario a ficheros: Al comienzo de cada fichero se añade un prólogo del fichero que explica el propósito del fichero y da otras informaciones.
• Comentarios a subprogramas: Al comienzo de cada subprograma se añade un prólogo del subprograma que explica el propósito del subprograma.
• Comentarios dentro del código: Estos comentarios se añaden junto a la definición de algunas variables (las más importantes), para explicar su propósito, y al comienzo de algunas secciones de código, especialmente complicadas, para explicar que hacen.

Los comentarios se pueden escribir en diferentes estilos dependiendo de su longitud y su propósito. En cualquier caso seguiremos las siguientes reglas generales:

• Los comentarios en general se escriben en líneas que no contienen código y antes del código que queremos clarificar. Esta regla se aplica siempre si el comentario tiene más de una línea.
• Sólo en dos casos se permite poner en la misma línea un comentario y una instrucción: comentarios a una definición de variable, que explica la finalidad de esta variable. Y un comentario para indicar final de una estructura del lenguaje.

Aquí vamos a describir como hacer comentarios dentro del código. Dentro de este tipo de comentarios se pueden distinguir:

• Comentarios en cajas: Usados para prólogos o para separar secciones.
• Separador de secciones: Son líneas que sirven para separar secciones, funciones, etc.
• Comentarios para bloques grandes: Se usan al comienzo de bloques de código grandes para describir esa porción de código.
• Comentarios cortos: Se usan para describir datos y casi siempre se escriben en la misma línea donde se define el dato. También se usan para indicar el final de una estructura.
• Comentarios para bloques pequeños: Se escriben para comentar bloques de instrucciones pequeños. Se colocan antes del bloque que comentan y a la misma altura de sangrado.

Comentarios en cajas:

Ejemplo: comentario tipo prólogo en una caja:

    (*************************************************************)
    (*      AUTOR: Nombre                                        *)
    (*                                                           *)
    (*      PROPOSITO:                                           *)
    (*                                                           *)
    (*************************************************************)

Separador de secciones:

Ejemplo: Separador de secciones.

    (**********************************************************)

Comentarios para bloques grandes:

Ejemplo: comentarios para bloques grandes de código.

    (*
     * Usar para comentarios a mas de un bloque de
     * sentencias.
     *)

En caso de utilizar este tipo de comentario, seguir las siguientes reglas:

• Utilizar uno o más tabuladores para separar la instrucción y el comentario.
• Si aparece más de un comentario en un bloque de código o bloque de datos, todos comienzan y terminan a la misma altura de tabulación.

Ejemplo: Comentarios en un bloque de datos.

    CONST
        MaxTeoria = 120; (* Maximo de alumnos por grupo teoría *)
        MaxPracticas = 24; (*Maximo de alumnos por grupo prácticas*)

Ejemplo: Comentarios al final de una estructura.

    FOR I := 1 TO Final DO
    BEGIN
        WHILE NOT(Correcto) DO
        BEGIN
            Correcto := FALSE;
            write('Introduce dato:');
            readln(Dato);
            IF Dato < 100 THEN
                Correcto := TRUE
        END; (* WHILE *)
        writeln
    END; (* FOR *)

Comentarios para bloques pequeños:

Ejemplo:

    (* Hallamos la nota media de todos los examenes *)
    FOR i := 1 TO NumAlumnos DO
        Suma := Suma + Nota[i];
    Media := Suma / NumAlumnos;

2.3. Uso de espacios y líneas en blanco

Los espacios en blanco facilitan la lectura y el mantenimiento de los programas. Los espacio en blanco que podemos utilizar son: líneas en blanco, carácter espacio, sangrado.

Línea en blanco:

Se utiliza para separar "párrafos" o secciones del código. Cuando leemos un programa entendemos que un fragmento de código entre dos líneas en blanco forma un conjunto con una cierta relación lógica.

Veamos como separar secciones o párrafos en el programa:

• Las secciones que forman un programa se separan con al menos una línea en blanco (declaración de variables, declaración de constantes, programa principal, …).
• Dentro de un subprograma se separan con una línea en blanco las secciones de declaraciones y el código del subprograma.
• Dentro de un subprograma se separan con una línea en blanco los fragmentos de instrucciones muy relacionadas entre sí (por ejemplo, conjunto de instrucciones que realizan una operación).

Los espacios en blanco sirven para facilitar la lectura de los elementos que forman una expresión. Los espacios en blanco se utilizan en los casos siguientes:

• Las variables y los operadores de una expresión deben estar separados por un elemento en blanco.
• Las lista de definición de variables, y las listas de parámetros de una función se deben separar por un espacio en blanco.

Ejemplos:

Espaciado correcto:

    Media := Suma / Cuenta;

Espaciado incorrecto:

    Media:=Suma/Cuenta;

Espaciado dentro de una lista de parámetros:

    concat(s1, s2)

El sangrado se utiliza para mostrar la estructura lógica del código. El sangrado óptimo es el formado por cuatro espacios. Es un compromiso entre una estructuración legible y la posibilidad de que alguna línea (con varios sangrados) del código supere el ancho de una línea de una hoja de papel o del monitor.

2.4. Elección adecuada de identificadores

Los identificadores que dan nombre a subprogramas, constantes, tipos o variables han de colaborar a la autodocumentación del programa, aportando información sobre el cometido que llevan a cabo. Para elegir nombre se deben seguir las siguientes recomendaciones generales:

• Elegir nombres comprensibles y en relación con la tarea que corresponda al objeto nombrado.
• Seguir un criterio uniforme con las abreviaturas de nombres.
• Utilizar prefijos y sufijos cuando sea necesario.
• Uso del carácter ‘_’ o de una letra mayúscula para distinguir las palabras que forman un identificador.
• Escribir un mismo identificador siempre de la misma forma, sin cambiar mayúsculas por minúsculas o viceversa.

Hay algunos nombres cortos que se usan muy habitualmente. El uso de estos nombres (y sólo de estos) es aceptable.

Ejemplo: nombres cortos aceptables.

    c, ch   caracteres
    i, j, k indices
    n       contadores
    p, q    punteros
    s, Cad  cadenas

3. Organización interna

En este apartado vamos a describir la forma correcta de escribir ciertas estructuras del lenguaje.

Las palabras reservadas CONST, TYPE y VAR deben comenzar en la misma columna de la cabecera y los elementos declarados se sangrarán a una misma columna. Las declaraciones deben seguir las siguientes reglas:

• Alinear los nombres de las variables de forma que la primera letra del nombre de cada variable esté en la misma columna.
• Definir una variable por línea junto con su comentario (si éste es necesario).

Como excepción a esta regla podemos agrupar en la misma línea variables auxiliares, contadores, etc.

• Si un grupo de subprogramas utiliza un parámetro o una variable interna para una labor semejante llamar con el mismo nombre a esa variables en todas las funciones.
• No utilizar nombres para variables internas que sean iguales a nombres de variables globales.

La forma que tiene Pascal de agrupar instrucciones en bloques es utilizar los parentizadores BEGIN-END. Su colocación se debe hacer en líneas reservadas para cada uno de ellos, sin ninguna otra instrucción en esa línea. Ambos deben ir en la misma columna que la instrucción de la que dependen.

Ejemplo:

    FOR i := 1 TO N DO
    BEGIN
        Vect[i] := Vect2[i];
        Suma := Suma + Vect[i]
    END

La sentencia o sentencias después de THEN y ELSE van siempre en una nueva línea sangrada:

    IF expresión THEN
        sentencia
    ELSE
        otra_sentencia;

IF expresión THEN
BEGIN
    sentencia1;
    sentencia2
END
ELSE
BEGIN
    otra_sentencia1;
    otra_sentencia2
END;

Los valores asociados a la sentencia CASE irán en línea aparte sangrada. El bloque de sentencias asociado comenzará en la misma línea a continuación del valor. Todos los bloques de sentencias pertenecientes al CASE comenzarán en la misma columna.

    CASE expresión OF
        1   : BEGIN
                  sentencia1;
                  sentencia2
              END;
        2, 3: otra_sentencia
    END;

La sentencia o sentencias pertenecientes a la estructura de repetición (sentencias después del DO o REPEAT) van siempre en una nueva línea sangrada:

    WHILE expresión DO
        sentencia;

WHILE expresión DO
BEGIN
    sentencia1;
    sentencia2
END;

4. Portabilidad y eficiencia

Un código bien escrito debe poder ejecutarse en otras máquinas o plataformas haciendo un mínimo de cambios. Nuestro código debe ser lo más portable posible.

• Usar Pascal ISO en la medida de lo posible.
• Escribir código portable en principio. Considerar detalles de optimización sólo cuando sea necesario. Muchas veces la optimización es diferente según la plataforma o la máquina utilizada. En todo caso:
  a) documentar estos detalles para poder modificarlos si necesitamos cambiar el código de plataforma.
  b) aislar la optimación de otras partes del código.
  
• Algunos subprogramas son no portables de forma inherente (por ejemplo ‘drivers’ de dispositivos suelen ser distintos en sistemas operativos distintos). Aislar este código del resto.
• Organizar el código en ficheros de forma que el código portable esté en ficheros distintos del código no portable.
• Computadoras distintas pueden tener un tamaño de tipos diferente. Utilizar la función sizeof() para asegurar la portabilidad en este caso.
• Evitar las multiplicaciones y divisiones hechas con desplazamientos de bits.
• No reemplazar los subprogramas estándar con subprogramas realizados por nosotros. Si no nos gusta una implementación de un subprograma estándar realizar un subprograma semejante pero con otro nombre.
• Utilizar las directivas de compilación condicional para mejorar la portabilidad del código.

Reglas para mejorar la eficiencia:

• Recordar que el código debe ser mantenido.
• Si la eficiencia del programa no es crítica sustituir instrucciones rápidas por instrucciones comprensibles.
• Si la eficiencia es importante (sistemas en tiempo real) y es necesario utilizar expresiones no comprensibles y muy complicadas pero rápidas, añadir comentarios que ayuden a comprender el código.
• Reducir al mínimo las operaciones de entrada/salida.
• Liberar memoria tan pronto como sea posible.
• Cuando se pasan estructuras grandes a un subprograma, hacerlo por referencia. Esto evita manipular datos sobre la pila y hace la ejecución más rápida.