Metodología de Programación y documentación

Introducción

El proyecto labSession requiere de muchas horas de trabajo en equipo y continuas revisiones. Por ese motivo es indispensable atender a tiempo las propuestas e implementaciones.

El estilo de programación en un lenguaje de programación como C se refiere a los aspectos que influyen en la comprensión del programa por parte de las personas, por ejemplo, la forma organizar las llaves de bloque, la nomenclatura de variables, el formato de comentarios etc.

Dichos aspectos no suelen afectar el funcionamiento del programa, pero resultan vitales a la hora de transmitir la relación problema/solución, facilitar la corrección de errores y adaptar el programa a nuevos requisitos.

A continuación se enumeran una serie de recomendaciones orientadas a reafirmar un estilo de programación uniforme:

Licencia

El proyecto adoptó la Licencia pública GNU (en español) para distribuir el programa, por lo tanto cada fichero fuente del programa debe incluir una nota como la siguiente:

labSession - administrador de sesiones
Copyright (c) 2005, 2006 Hugo Ruscitti

labSession is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

labSession is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

Tabulaciones

Los bloques y estructuras de control se destacan utilizando caracteres de tabulación, en labSession optamos por una mezcla del estilo BSD y ANSI:

Funciones

int promedio (int a, int b)
{
        return (a + b) / 2;
}

Estructura condicional IF

if (condicion)
{
        sentencia1;
        
        if (otra_condicion)
        {
                sentencia1;
        } 
        else
        {
                sentencia2;
        }
        
}

Otras estructuras de control y repetición

switch (cond)
{
     case 1:
        sentencia1;
        sentencia2;
        break;

     default:
        sentencia3
        break;
}

while (cond)
{
        sentencia1;
}

for (i = 0; i < n; i ++)
{
        sentencia1;
        sentencia2;
}

En donde las tabulaciones se realizan únicamente utilizando el carácter TAB (no espacios).

Limite de columnas

El espacio de trabajo suele estar delimitado por la cantidad de columnas que proveen la mayoría de los terminales de texto, unas 80 columnas visibles en pantalla. No es aconsejable exceder esa cantidad de columnas; Si es necesario configure su editor/terminal a 80 columnas.

Un comando útil para trabajar con xterm en el sistema gráfico x-window a 800x600 pixeles es:

xterm -bg black -fg white -fs 11 -fa bold -geometry 80x29+40+40

Ante la imposibilidad de incluir una sentencia de código en 80 columnas debería contemplar la posibilidad de modularizar aún mas el código, si no encuentra otra forma de hacerlo utilice '\' al final de la linea y continúe en la siguiente:

void funcion (void)
{
        if (condicion_muy_larga1 ..... \
        && condicion_n)
        {
                sentencia1;
                sentencia2;
        }
}

Nota:

Cuando limitamos la cantidad de columnas a 80 asumimos que los caracteres de tabulación (TAB) representan una longitud de 8 columnas.

Documentación en linea

Para desarrollar la documentación del proyecto optamos por utilizar el sistema Doxygen http://www.doxygen.org/index.html. Doxygen es un sistema de documentación que recupera información directamente desde los comentarios del código fuente y genera una completa especificación de funciones y estructuras de datos.

También utilizamos Doxygen para generar otra clase de documentación, como esta guía.

Para utilizar el sistema de documentación debe añadir comentarios especiales antes de cada función y estructura de datos. El resto de los comentarios (dentro del cuerpo de las funciones) no son necesarios; el contenido de cada función debería ser simple y breve, el identificador de función y su comentario serán suficientes.

[inicio]
 \brief emite la información de un usuario en particular
 \param adm socket que lo relaciona con el administrador
 \param cliente nodo del cliente con información
 \return 1 si no puede enviar el mensaje
[final]
int servidor_enviar_datos_cliente (TCPsocket adm, struct nodo * cliente)
{
        [...]

De donde [inicio] se reemplaza por "/ *!" y [final] por "* /". Puede consultar algún archivo del directorio src ante dudas.

Nomenclatura de variables, funciones y estructuras

Variables

Para elegir el nombre de variables se utilizan palabras completas y descriptivas. Puede utilizar mas de una palabra como identificador, pero siempre divididas por '_' (guión bajo).

char * respuesta;
int en_sesion;

Las variables de uso frecuentes, como los índices de vector o variables temporales se pueden nombrar de manera mas sencilla:

char buffer [1024]      -> cadena de almacenamiento temporal
int tmp                 -> variable temporal
int i                   -> índice para `recorrer` vectores o ciclos `for`
int j                   -> ídem. anterior, pero para columnas de matrices
struct <...> * data     -> referencia a un módulo (ver a continuación)

Struct

Las estructuras de datos se declaran como propias, utilizando la palabra reservada typedef. Su nombre debe comenzar con letra mayúscula:

typedef struct cliente
{
        int codigo;
        char * usuario;
        int sesiones_utilizadas;
} Cliente;

Todo programa del sistema cuenta con una estructura propia, el programa Login (ver login) cuenta con su propio `struct` Login. Así, todas los operaciones vinculadas a un programa suelen incluir una referencia a su estructura, por ejemplo:

void login_mostrar_error_conexion (Login * data, char * ip, int puerto)
{
        char mensaje [200];
        
        sprintf (mensaje, "Imposible conectar a (%s:%d)", ip, puerto);

        mostrar_dialogo_bloqueante (data->form1.ventana, GTK_MESSAGE_ERROR, \
                        mensaje, FALSE);
}

Note que utilizamos data como identificador de módulo. La mayoría de las funciones se encontrarán vinculadas a una estructura (ver siguiente).

Funciones

Para las funciones se utiliza una nomenclatura similar a la variables pero en verbo infinitivo, ya que las funciones representan operaciones.

void quitar_barra_n (char * buffer)
{
        if (buffer [strlen (buffer) - 1] == '\n')
        buffer [strlen (buffer) - 1] = '\0';
}

Por lo general, las funciones de labSession están asociadas a un módulo en particular, para reflejar dicha asociación se utiliza como prefijo el nombre de módulo:

int servidor_iniciar (Servidor * datos, int argc, char * argv []);
void servidor_terminar (Servidor * data)

void cliente_atender_login (Cliente * data);
int cliente_cargar_opciones (Cliente * data, int argc, char * argv []);

En todos los casos se utiliza como primer argumento un puntero al módulo en cuestión. A fin de evitar ambigüedades, el primer parámetro de cada función se identifica como data.

Enum

Las enumeraciones y constantes se nombran en mayúsculas. También se evita, de ser posible, convertir el tipo de una enumeración a valor numérico, ya que al convertirlas se pierde la posibilidad de capturar errores utilizando el mismo pre-procesador de C.

enum mensaje {
        MSG_NULL,
        MSG_OK,
        MSG_ERROR
        <...>
        };

---