Estilo de programación

‘El estilo de programación’ se refiere a la forma en que se da formato al código fuente. Para C, esto involucra la forma en que se ubican las llaves, se indenta el código y se utilizan los paréntesis. GNOME tiene una mezcla de estilos de programación y no se obliga el uso de ninguno de ellos. Lo más importante es que el código sea consistente dentro de un programa o una biblioteca — el código con un formato desordenado no es aceptable debido a que es difícil de leer.

Cuando escribas un nuevo programa o biblioteca, sigue un estilo consistente de ubicación de llaves y de indentación. Si no tienes ninguna preferencia personal de estilo, recomendamos el estilo de programación del núcleo de Linux o el estilo de programación de GNU.

Lee el nodo de info (Standards)Writing C en la documentación de GNU. Luego, obtén el código fuente de Linux y lee el archivo linux/Documentation/CodingStyle, e ignora los chistes de Linus. Estos dos documentos te darán una buena idea de nuestras recomendaciones para el código de GNOME.

Estilo de indentación

Para el código del núcleo de GNOME preferimos el estilo de indentación del núcleo de Linux. Usa tabuladores de 8 espacios para la indentación.

Usar tabuladores de 8 espacios para indentación proporciona un número de beneficios. Permite que el código sea más fácil de leer, ya que la indentación se marca claramente. También ayuda a mantener el código ordenado forzando a dividir funciones en trozos más modulares y bien definidos — si la indentación va más allá del margen derecho, significa que la función está mal diseñada y que debiera dividirse para hacerla más modular o bien, repensarla.

Los tabuladores de 8 espacios para indentación también ayudan al diseño de funciones que encajen bien en la pantalla, lo cual significa que las personas puedan entender el código sin tener que desplazarse atrás y adelante para entenderlo.

Si usas Emacs, entonces puedes seleccionar el estilo de indentación del núcleo de Linux incluyendo en el archivo .emacs lo siguiente:

(add-hook 'c-mode-common-hook
          (lambda ()
            (c-set-style "k&r")
            (setq c-basic-offset 8)))

En los nuevos Emacs o con el nuevo cc-mode, puedes ser capaz de hacerlo más simple con:

(add-hook 'c-mode-common-hook
          (lambda ()
            (c-set-style "linux")))

El estilo de indentación de GNU es el predeterminado para Emacs, así que no es necesario agregar nada en el archivo .emacs para habilitarlo. Si deseas seleccionarlo explícitamente, sustituye «gnu» por «linux» en el ejemplo anterior.

Si usas Vim, entonces puedes seleccionar el estilo de indentación del núcleo de Linux incluyendo el siguiente fragmento en el archivo .vimrc:

set ts=8
if !exists("autocommands_loaded")
  let autocommands_loaded = 1
  augroup C
      autocmd BufRead *.c set cindent
  augroup END
endif

Como alternativa puedes seleccionar el estilo de indentación de GNU en Vim usando lo siguiente en el archivo .vimrc: [1]:

augroup C
   autocmd BufRead *.c set cinoptions={.5s,:.5s,+.5s,t0,g0,^-2,e-2,n-2,p2s,(0,=.5s formatoptions=croql cindent shiftwidth=4 tabstop=8
augroup END

Nota

Si sabe personalizar el estilo de indentación en otros editores populares, por favor háganoslo saber y así podemos expandir este documento.

Convenciones de nombres

Es importante seguir una buena convención de nombres para los símbolos de los programas. Es específicamente importante para las bibliotecas, ya que no debería ensuciarse el espacio de nombres global — es muy molesto cuando una biblioteca tiene símbolos nombrados desordenadamente que chocan con nombres que pueda querer usar en sus programas.

Los nombres de las funciones deberían ser de la forma modulo_submodulo_operacion, por ejemplo, gnome_canvas_set_scroll_region o gnome_mime_get_keys. Esta convención elimina las colisiones de nombres de símbolos entre módulos. Es muy importante para las bibliotecas.

Los símbolos deben tener nombres descriptivos. Como Linus dice, no use cntusr(), sino que use count_active_users(). Esto permite que el código sea más fácil de leer y casi se auto documenta.

Intente usar las mismas convenciones de nombre que tienen GTK+ y las bibliotecas de GNOME:

  • Los nombres de las funciones en minúsculas, con líneas de subrayado para separar palabras, tal como: gnome_canvas_set_scroll_region(), gnome_mime_get_keys().

  • Las macros y las enumeraciones en mayúsculas, con líneas de subrayado para separar palabras, tal como: GNOMEUIINFO_SUBTREE() para una macro y GNOME_INTERACT_NONE para un valor enumerado.

  • Los nombres de tipos y estructuras usan una mezcla de mayúsculas y minúsculas, tal como: GnomeCanvasItem, GnomeIconList.

Al utilizar líneas de subrayado para separar palabras el código estará menos apretado y facilita la edición, ya que puede usar las secuencias de teclas que permiten navegar entre palabras más rápidamente en cualquier editor.

Si estás escribiendo una biblioteca, entonces puedes necesitar exportar símbolos que serán usados sólo dentro de la biblioteca. Por ejemplo, dos de los archivos objeto que componen la biblioteca libfoo.so pueden requerir acceder a símbolos ubicados en el otro archivo, pero se tiene la intención que éstos símbolos no sean utilizados desde los programas de usuario. En este caso, coloca una línea de subrayado antes del nombre de la función y haz que la primera palabra siga la convención estándar módulo/submódulo. Por ejemplo, podrías tener una función llamada _foo_internal_frobnicate().

Consistencia entre nombres

Es importante que las variables se nombren de manera consistente. Por ejemplo, un módulo que manipula una lista puedes elegir nombrar las variables que mantienen un puntero a la lista como «l», por elegancia y simplicidad. Sin embargo, es importante que un módulo que manipula widgets y tamaños no use variables llamadas «w» tanto para widgets y anchos («width») (como en valores de ancho/alto); esto podría hacer que el código sea inconsistente y difícil de leer.

Por supuesto, nombre muy cortos y elegantes solamente deberían ser usados para variables locales de funciones. Nunca llame una variable global «x»; use un nombre más largo que indique lo que significa.

Limpieza

El código de GNOME debe ser tan limpio como sea posible. Esto implica usar un estilo de indentación consistente y una buena convención para nombrar símbolos, como se ha indicado anteriormente. Esto también implica lo siguiente.

Aprender el uso correcto de la palabra reservada static. No declarar todos los símbolos como globales. Esto tiene la ventaja de poder usar nombres más cortos dentro de las funciones en un sólo archivo fuente, ya que no son globalmente visibles y por consiguiente no necesitas emplear el prefijo módulo/submódulo.

Aprender el uso correcto de la palabra reservada const. Úsala consistentemente, así permitirás al compilador que atrape muchos errores estúpidos.

Si tienes una función que retorna un puntero a un dato interno que se supone que el usuario no debe liberar, deberías usar el modificador const. Este avisará al usuario si intenta hacer alguna operación incorrecta, por ejemplo:

const char *gnome_mime_get_info (const char *info);

El compilador avisará si el usuario intenta liberar la cadena retornada. Esto puede atrapar muchos errores.

Si tienes «valores mágicos» en el programa o biblioteca, usa macros que los definan en vez de usarlos directamente en el código:

/* Amount of padding for GUI elements */
#define GNOME_PAD          8
#define GNOME_PAD_SMALL    4
#define GNOME_PAD_BIG      12

Si tienes una lista de valores posibles para una variable, no uses macros para ellas, usa enum para darle un nombre de tipo — esto permite disponer de nombres simbólicos en un depurador. Además, no uses «int» para almacenar un valor enumerado; usa el tipo enum. Esto le permite al compilador atrapar los errores por tí, permitiéndole al depurador mostrar los valores apropiados y hacer obvios los valores que una variable puede tomar. A continuación un ejemplo:

/* Shadow types */
typedef enum {
	GTK_SHADOW_NONE,
	GTK_SHADOW_IN,
	GTK_SHADOW_OUT,
	GTK_SHADOW_ETCHED_IN,
	GTK_SHADOW_ETCHED_OUT
} GtkShadowType;

void gtk_frame_set_shadow_type (GtkFrame *frame, GtkShadowType type);

Si define un conjunto de valores para un campo de bits, haz lo siguiente:


/* Update flags for items */
enum {
	GNOME_CANVAS_UPDATE_REQUESTED  = 1 << 0,
	GNOME_CANVAS_UPDATE_AFFINE     = 1 << 1,
	GNOME_CANVAS_UPDATE_CLIP       = 1 << 2,
	GNOME_CANVAS_UPDATE_VISIBILITY = 1 << 3,
	GNOME_CANVAS_UPDATE_IS_VISIBLE = 1 << 4
};

Esto hace más fácil modificar la lista de valores y menos propenso a error que especificando los valores a mano. También permite usar estos valores como símbolos en un depurador.

No escribas código ofuscado, intenta que sea espartano. Para clarificar una expresión, no uses más paréntesis que los necesarios. Usa espacios antes de los paréntesis y después de las comas y también alrededor de los operadores binarios.

No escribas hacks en el código. En vez de escribir un hack feo, reescribe el código para que quede limpio, extensible y mantenible.

Asegúrate de que el código compila absolutamente sin ningún aviso del compilador. Esto te ayudará a atrapar errores estúpidos. Usa los prototipos de las funciones en los archivos de encabezados de forma consistente.

Dentro de GNOME puedes usar la macro de Autoconf GNOME_COMPILE_WARNINGS en el archivo configure.in. Esto permitirá contar con un buen conjunto de avisos del compilador de una manera portable.

Comenta el código. Coloca comentarios antes de cada función para decir que hace. No digas cómo lo hace a menos que sea absolutamente necesario; debería ser obvio al leer el código. Si no lo fuera, entonces puedes desear reescribirla hasta que sea fácil de entender.

Cuando documentes las funciones de la API de una biblioteca, sigue las directrices indicadas en el archivo gnome-libs/devel-docs/api-comment-style.txt. Esto permite que el código fuente pueda proporcionar documentación en línea, que posteriormente se extrae mediante el sistema gtk-doc para crear un manual DocBook de forma automática.

Consideraciones de portabilidad

Se construye GNOME en muchas plataformas diferentes. Se puede asumir que serán plataformas más o menos tipo Unix; hasta el momento GNOME no ha sido portado a sistema no-Unix, así que se puede asumir que los servicios estándares de Unix estarán disponibles.[2]

Recuerda que el mundo no es tu propio equipo con GNU/Linux; las gente realmente usa otros tipos de máquinas.

Intenta no usar extensiones específicas de GCC debido a que éstas no funcionarán con otros compiladores. Si realmente debes hacer uso de tal cosa, ve la forma en que se hace en Glib con el conjunto de macros G_GNUC; asegúrate también de incluir código que funcione con compiladores ISO C. Si sólo tienes disponible GCC, aprende a usar las opciones -ansi -pedantic que permiten probar código sospechoso.

Recuerda que algunas plataformas no disponen de GCC o que GDB puede ser inusable en ellos, y se querrán usar otros compiladores y depuradores.

Tópicos relacionados con GTK+

GTK+ permite hacer mucha magia y ofuscación con manejadores de señal, pasar cerraduras y conjuntos de datos. Si te encuentras utilizando muchos gtk_object_set_data() en un mismo lugar, o estas pasando estados de forma extraña a través de manejadores de señales, reescribe el código. Si necesitas adjuntar muchos datos a un objeto en particular, entonces es un buen candidato para una nueva clase derivada, que no sólo hará al código más limpio, sino que también lo hará más extensible.

Mucha de la heurística en manejadores de eventos complicadas a menudo se pueden reemplazar limpiando el código a través de una máquina de estados. Esto es útil cuando se quieren implementar cosas truculentas como selección y comportamientos de arrastrado, y hará al código más fácil de depurar y extender.



[1] Gracias a Tomas Ögren por proporcionar este código.

[2] ¿Servicios estándar de Unix? Por supuesto que estamos bromeando.