UC3M

Los nombres de variables, funciones y ficheros deben ser cortos, descriptivos y concretos.

struct tcp_header header;
bool is_enabled;

int parse_xml_file(FILE * file);
void init_user_interface(void);

list.c
xml_parser.c
math.c

struct tcp_header b;
bool tmp;

int open_xml_file_and_get_content(FILE * f);
void ui(void);

types.h
utils.c
code3.c

Los nombres de variables y funciones deben escribirse en minúsculas y, si se componen de varias palabras, cada palabra debe separarse mediante el símbolo “_” (guión bajo). Hay otras tendencias tales como usar mayúsculas para separar palabras (estilo que se conoce como “CamelCase”). En este curso adoptamos la separación por guiones bajos. Para mostrar por qué es preferible usar minúsculas con subrayado lee las dos frases siguientes:

YoTeniaUnTanganitoVerdeAlQueLeQuedabaGrandeLaCamiseta

yo_tenia_un_tanganito_verde_al_que_le_quedaba_grande_la_camiseta

¿Cuál de las dos requiere menos concentración del lector? De todas formas, si la librería estándar del lenguaje que usas está escrita con estilo CamelCase (como es el caso de Java), debes usar este convenio por consistencia. Pero no es el caso del lenguaje C, con lo que adoptaremos la separación por guiones bajos.

Las macros y constantes deben escribirse en mayúsculas para distinguirlas de variables y funciones.

Las constantes y enumerados públicos deben llevar un prefijo corto de 3 o 4 letras que identifique al módulo que los define (un módulo es un conjunto de datos y funciones contenidos en varios ficheros). Esto evita conflicto de nombres entre distintos módulos. Por ejemplo:

#define LST_MAX_SIZE 32
enum
{
    MSG_CONNECT,
    MSG_ACK,
    MSG_DATA,
    MSG_RELEASE
} message_type_t;

El código se debe indentar para representar la estructura lógica del programa. Deben usarse tabuladores para indentar, nunca espacios. La indentación que se adopta en el curso es de 4 espacios en blanco. Te recomendamos configurar el editor de código para que el tabulador introduzca el equivalente a 4 espacios.

El motivo de usar tabuladores en lugar de espacios es que de esta forma, cada desarrollador puede visualizar el código con el nivel de indentación que más cómodo le resulte. Sólo hay que configurar el editor para representar el tabulador con el nivel de profundidad que se desee.

Las llaves deben colocarse según el estándar Allman, también conocido como BSD, es decir, en la línea siguiente a un if, o a un while (ver ejemplos al final de la sección).

Debe haber un espacio en blanco antes y después de los operadores de comparación, asignación, etc. También debe haber un espacio entre las palabras clave (for, while, if, return, etc.) y las expresiones que le siguen.

El contenido de las funciones debe caber entero en pantalla. No debería ser necesario hacer scroll para ver el contenido completo, aunque en ocasiones puede ser necesario extenderse. En cualquier caso, nunca se deben escribir funciones que excedan el espacio de dos pantallas.

Las líneas no deben tener una longitud mayor a 80 letras. Este convenio facilita la visualización de varios ficheros simultáneamente en la pantalla. A continuación mostramos dos fragmentos de código bien y mal formateado::

int db_sync(void)
{
    int i, retval = 0, result = 0;

    for (i = 0; i < P_SIZE; i++)
    {
        if (param_info[i].dirty && param_info[i].sync_cb)
        {
            retval = param_info[i].sync_cb(i, param_db[i]);
            result |= retval;

            if (retval == 0)
                param_info[i].dirty = false;
        }
        else
        {
            LOG_WARNING(“No callback for param %d”, i);
        }
    }

    return result;
}

int db_sync(void)
{
  int i, retval = 0, result = 0;

  for (i = 0; i < P_SIZE; i++){
  if (param_info[i].dirty && param_info[i].sync_cb) {
    retval = param_info[i].sync_cb(i, param_db[i]);
    result |= retval;
    if (retval == 0)
    param_info[i].dirty = false;
  } else {
  LOG_WARNING(“No callback for param %d”, i);
  }
  }
  return result;}

Deben usarse macros para definir tamaños de arrays de forma que sean fáciles de leer y modificar. Es frecuente usar las macros también para otro tipo de constantes en el código.

#define TIMEOUT_SECS  120
#define MAX_LINE_SIZE 80

char input_line[MAX_LINE_SIZE];
timer = set_timer(TIMEOUT_SECS);

En el caso de arrays, el motivo es simple: en origen, C no permite usar variables para dimensionar un array. La única manera de usar constantes simbólicas con ellos es usar el preprocesador.

Todas las funciones definidas en un fichero “.c”, ya sean públicas o privadas (static) deben llevar un comentario encima que diga en una línea o dos qué es lo que hacen. También se pueden añadir en este encabezado comentarios sobre particularidades del funcionamiento general de la función.

/* 
 * db_sync()
 * Synchronizes the internal database with the firmware files by storing
 * modified parameters on permanent storage.
 *
 * Any parameter marked as "dirty" will be dumped by calling its associated
 * sync callback.
 */
int db_sync(void)
{
...
}

Estos comentarios son para que una persona que esté explorando el código pueda entender qué hace una función sin tener que estudiarla en profundidad. Este breve comentario en el encabezado de la función debe apoyarse a su vez en un nombre de función descriptivo.

Deben añadirse comentarios a partes no triviales del código. En muy raras ocasiones es necesario comentar líneas individuales, pues si el código está bien escrito, no es necesario repetir en un comentario lo que ya está escrito en C.

/* Call synchronization callback for parameters
 * marked “dirty”. Clear dirty flag if callback
 * succeeds. */
if (param_info[i].dirty && param_info[i].sync_cb)
{
    retval = param_info[i].sync_cb(i, param_db[i]);
    result |= retval;

    if (retval == 0)
    {
        param_info[i].dirty = false;
    }
}

if (param_info[i].dirty && param_info[i].sync_cb)
{
  /* Call sync_cb */
  retval = param_info[i].sync_cb(i, param_db[i]);
  result |= retval;

  if (retval == 0)
  {
    /* Set dirty flag to false ª/
    param_info[i].dirty = false;
  }
}

El código en C se organiza en ficheros con extensiones “.c” y “.h”. Para cada fichero “.c” debe existir un “.h” con el mismo nombre (list.c, list.h). A esta pareja de ficheros se la denomina informalmente módulo. Los ficheros “.c” no son únicamente un conjunto de funciones. La clave para organizar el código en varios ficheros y no tener problemas de dependencias cruzadas (el compilador protesta porque desconoce un símbolo o definición que está en otro fichero), es entender que lo que en otros lenguajes de programación se maneja de manera natural como objetos, en C suelen ser los módulos (aunque muchísimo más simplificado, claro).

Cada módulo (u “objeto” si se quiere) tiene un conjunto de funciones cuyos prototipos conforman la interfaz pública que está definida en el fichero “.h”. El fichero “.c” contiene la implementación de estas funciones y en algunos casos variables y funciones que sólo son accesible dentro del “.c”. Los prototipos de las funciones que se consideran públicas (se pueden utilizar desde cualquier otro sitio del programa) se ponen en el “.h” para que otros módulos puedan usarlas utilizando al comienzo de su fichero la directiva #include. Las otras funciones, las privadas, se incluyen sólo dentro del “.c” definidas con el prefijo static y así no pueden ser invocadas desde otro fichero.

Cada fichero “.c” debe tener al comienzo una directiva include para incluir a su propio “.h” (por ejemplo, list.c debe tener #include "list.h"). Esto se hace para evitar inconsistencias entre la definición de variables o prototipos de las funciones públicas en el “.c”, y la declaración de su prototipo en el “.h”. Si se incluye el “.h” en su correspondiente “.c”, el compilador puede detectar conflictos de tipo.

Los ficheros “.h” deben contener sólo declaraciones públicas: tipos, constantes, variables globales y prototipos de funciones diseñados para ser usados desde fuera del módulo. Todo lo demás se debe incluir en el “.c”

Todo fichero “.h” debe contener una guarda para evitar inclusiones múltiples. Una guarda se implementa rodeando el contenido del fichero entero entre #ifndef SÍMBOLO y #endif. El nombre del símbolo debe ser único para ese fichero (se recomienda utilizar el propio nombre del fichero con guiones bajos). A continuación de la primera línea que tiene el #ifndef debe ir la directiva #define seguida del mismo símbolo idéntico que se ha incluido en la línea anterior. Tras esta directiva se incluye el contenido del fichero “.h” con normalidad. A continuación se muestra un ejemplo de guarda implementada en el fichero con nombre list.h.

#ifndef _LIST_H
#define _LIST_H_
...
... contenido del fichero list.h ...
...
#endif /* _LIST_H_ */

Los ficheros “.h” sólo deben contener las directivas #include imprescindibles para compilar por sí mismos. La mejor forma para probar que un “.h” incluye sólo lo imprescindible es escribir un pequeño main como el que se muestra a continuación:

#include "list.h"
int main(void)
{
    return 0;
}

Es obligatorio definir como static las variables y funciones privadas (que no pueden usarse en ningún otro sitio). Las variables globales de un módulo, deben definirse juntas al comienzo del fichero para poder identificarlas de un vistazo. En ningún caso deben estar desperdigadas por el medio del fichero. Una consecuencia de esta regla es que conviene separar la definición de estructuras de la declaración de variables globales de tipo struct. Por un lado se definen los tipos (si son públicos en el “.h”, si no lo son en el “.c”), y por otro se declaran las variables globales del módulo haciendo uso de esos tipos.

#include "param_db.h"

struct param_entry
{
    char param[PARAM_MAX_LEN];
    char value[VALUE_MAX_LEN];
    char default[VALUE_MAX_LEN];
};

struct param_list
{
    struct param_entry param;
    struct list_node *next;
};

/* Global Variables */
int error_code;
static struct param_list *param_map;

#include "param_db.h"

struct param_entry
{
    char param[PARAM_MAX_LEN];
    char value[VALUE_MAX_LEN];
    char default[VALUE_MAX_LEN];
};

static struct param_list
{
    struct param_entry param;
    struct list_node *next;
} *param_map;

int error_code;