30/1/2019 Estilo de programación

Guía de programación de GNOME

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
https://calcifer.org/documentos/programming-guidelines/code-style.html 1/4
30/1/2019 Estilo de programación

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:

https://calcifer.org/documentos/programming-guidelines/code-style.html 2/4
30/1/2019 Estilo de programación

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]

https://calcifer.org/documentos/programming-guidelines/code-style.html 3/4
30/1/2019 Estilo de programación

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.

<< La importancia de escribir buen código Corrección y robustez >>

https://calcifer.org/documentos/programming-guidelines/code-style.html 4/4