Lenguaje C: Guía de Estilo Resumida

Transcripción

1 Lenguaje C: Guía de Estilo Resumida Antón Gómez, octubre 2010 Introducción Esta guía propone una serie de reglas básicas, estudiadas para favorecer la escritura de código limpio y fácil de leer. Para entender por qué es necesario observar ciertas normas a la hora de escribir software, es importante ser consciente de las dimensiones que tienen los proyectos de software más o menos complejos. Veamos algunos ejemplos cotidianos: Aplicación Descripción Líneas de código Windows XP Sistema operativo completo 40 millones Kernel de Linux Núcleo de sistema operativo 8.4 millones Subversion Sistema de control de versiones 417 K Google Chrome Navegador web 1.5 millones (C++) 1.4 millones (C) PHP Motor de scripting para páginas web activas 800 K The Gimp Edición gráfica 675 K VLC Media Player Reproductor multimedia 341 K (C), 93 K (C++) Cuando un programa está compuesto por varios cientos de miles de líneas, o incluso varios millones, es de suma importancia escribir el código de forma que sea muy sencillo de leer. De lo contrario, es necesario invertir una enorme cantidad de esfuerzo (quien dice esfuerzo dice dinero) para hacer cualquier modificación, por simple que parezca. También hay que entender que el código normalmente se escribe una vez, pero se lee decenas de veces: para buscar problemas, para entender cómo funciona antes de modificarlo, o para escribir otros módulos que interactúan con él. La norma en la industria es que el código lo va a estar leyendo constantemente gente que no participó en su escritura.

2 Organización del código El código en C se organiza en ficheros.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 módulo. Los ficheros.c no son sacos de funciones. La clave para organizar el código en varios ficheros y no tener problemas de dependencias cruzadas, es entender que lo que en lenguajes más modernos se maneja de manera natural como "objetos", en C son los módulos. Cada módulo (u "objeto" si se quiere) tiene una interfaz pública definida en su.h, y una serie de variables y funciones privadas escondidas dentro del.c. Las declaraciones públicas se ponen en el.h para que otros módulos puedan usarlas haciendo #include, y las privadas se quedan dentro del.c definidas como static para que nadie las pueda usar desde fuera. Cada fichero.c debe incluir a su propio.h (list.c haría #include de list.h). 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 mete en el.c Todo fichero.h debe contener guardas para evitar inclusiones múltiples. #ifndef _LIST_H_ #define _LIST_H_... interfaz pública del módulo... #endif /* _LIST_H_ */ 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. #include param_db.h #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; ; /* Globals */ int error_code; static struct param_list * param_map; 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;

3 Identificadores Los identificadores de variables y funciones deben ser cortos, descriptivos y concretos. Los nombres de los ficheros también. 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 identificadores de variables y funciones deben escribirse en minúsculas y, si se componen de varias palabras, cada palabra debe separarse mediante el caracter '_'. Las macros y constantes deben escribirse en mayúsculas para distinguirlas de variables y funciones. Formato El código se debe indentar para representar la estructura lógica del programa. Deben usarse tabuladores para indentar, nunca espacios. Se recomienda configurar el editor de código para visualizar el tabulador con 4 espacios. 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, por ejemplo. Ver ejemplos al final de la sección. 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 pasar de la columna 80.

4 Ejemplo código bien formateado: int i, retval = 0, result = 0; for (i = 0; i < P_SIZE; i++) else LOG_WARNING( No callback for param %d, i); return result; Ejemplo de código mal formateado: int i, retval = 0, result = 0; for (i = 0; i < P_SIZE; i++) else LOG_WARNING( No callback for param %d, i); return result;

5 Uso del preprocesador Deben usarse macros para definir tamaños de arrays de forma que sean fáciles de leer y modificar. Es frecuente usarlas 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); Comentarios 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. */ 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 * succeedes. */ /* Call sync_cb */ /* Set dirty flag to false ª/