Este documento presenta el estilo de codificación preferido para los programas en C en GNOME. Mientras que el estilo de codificación es en gran medida una cuestión de gustos, en GNOME estamos a favor de un estilo de codificación que promueve la consistencia, legibilidad y mantenibilidad.
Presentamos ejemplos de buen estilo de codificación así como ejemplos de mal estilo que no es aceptable en GNOME. Intente enviar parches que se ajusten al estilo de codificación de GNOME; esto indica que ha hecho sus deberes respecto al objetivo del proyecto de mantenibilidad a largo plazo. ¡Los parches con el estilo de codificación de GNOME serán también más fáciles de revisar!
Este documento es para código C. Para otros lenguajes, compruebe la página principal de las directrices de programación de GNOME.
Estas directrices están fuertemente inspiradas por el documento GTK’s CODING STYLE, el Linux Kernel’s CodingStyle, y el GNU Coding Standards. Estos son pequeñas variaciones cada uno de otro, con modificaciones particulares para las necesidades y cultura particulares de cada proyecto, y la versión de GNOME no es diferente.
La única regla más importante al escribir código es: revise el código existente y trate de imitarlo.
Como mantenedor es desalentador recibir un parche que está obviamente en un estilo de codificación diferente al código ya existente. Esto es una falta de respeto, como cuando alguien pisa en una casa impecablemente limpia con los zapatos llenos de barro.
Por lo tanto, sea lo que sea lo que este documento recomienda, si ya hay código y lo está parcheando, mantenga su estilo actual coherente incluso si no es su estilo favorito.
Intente usar líneas de código de entre 80 y 120 caracteres de largo. Esta cantidad de texto es fácil de ajustar en la mayoría de monitores con un tamaño de tipografía decente. Las líneas más largas se vuelve difíciles de leer, y significan que probablemente debería reestructurar su código. Si tiene demasiados niveles de sangrado, significa que debería arreglar su código de alguna manera.
En general hay dos estilos de sangrado preferidos para el código en GNOME.
Estilo del kernel de Linux. Los tabuladores con una longitud de 8 caracteres se usan para el sangrado, con K&R el lugar de las llaves:
for (i = 0; i < num_elements; i++) {
foo[i] = foo[i] + 42;
if (foo[i] < 35) {
printf ("Foo!");
foo[i]--;
} else {
printf ("Bar!");
foo[i]++;
}
}
Estilo GNU. Cada nuevo nivel se sangra con dos espacios, las llaves van en una línea solas, y se sangran también.
for (i = 0; i < num_elements; i++)
{
foo[i] = foo[i] + 42;
if (foo[i] < 35)
{
printf ("Foo!");
foo[i]--;
}
else
{
printf ("Bar!");
foo[i]++;
}
}
Ambos estilos tienen sus pros y contras. Lo más importante es ser coherente con el código existente. Por ejemplo, la biblioteca GTK+, que es el kit de herramientas para widgets de GNOME, está escrita con el estilo GNU. Nautilus, el gestor de archivos de GNOME, está escrito con el estilo del kernel de Linux. Ambos estilos son perfectamente legibles y coherentes cuando se acostumbra a ellos.
Your first feeling when having to study or work on a piece of code that doesn’t have your preferred indentation style may be, how shall we put it, gut-wrenching. You should resist your inclination to reindent everything, or to use an inconsistent style for your patch. Remember the first rule: be consistent and respectful of that code’s customs, and your patches will have a much higher chance of being accepted without a lot of arguing about the right indentation style.
Nunca cambie el tamaño de los tabuladores en su editor; déjelos con 8 espacios. Cambiar el tamaño de los tabuladores significa que el código que no escribió estará perpetuamente mal alineado.
Instead, set the indentation size as appropriate for the code you are editing. When writing in something other than Linux kernel style, you may even want to tell your editor to automatically convert all tabs to 8 spaces, so that there is no ambiguity about the intended amount of space.
Las llaves no deberían usarse para bloques de una sola sentencia:
/* valid */
if (condition)
single_statement ();
else
another_single_statement (arg1);
The “no block for single statements” rule has only four exceptions:
In GNU style, if either side of an if-else statement has braces, both sides should, to match up indentation:
/* valid GNU style */
if (condition)
{
foo ();
bar ();
}
else
{
baz ();
}
/* invalid */
if (condition)
{
foo ();
bar ();
}
else
baz ();
If the single statement covers multiple lines, e.g. for functions with
many arguments, and it is followed by else or
else if:
/* valid Linux kernel style */
if (condition) {
a_single_statement_with_many_arguments (some_lengthy_argument,
another_lengthy_argument,
and_another_one,
plus_one);
} else
another_single_statement (arg1, arg2);
/* valid GNU style */
if (condition)
{
a_single_statement_with_many_arguments (some_lengthy_argument,
another_lengthy_argument,
and_another_one,
plus_one);
}
else
{
another_single_statement (arg1, arg2);
}
Si la condición se compone de varias líneas:
/* valid Linux kernel style */
if (condition1 ||
(condition2 && condition3) ||
condition4 ||
(condition5 && (condition6 || condition7))) {
a_single_statement ();
}
/* valid GNU style */
if (condition1 ||
(condition2 && condition3) ||
condition4 ||
(condition5 && (condition6 || condition7)))
{
a_single_statement ();
}
Note that such long conditions are usually hard to understand. A good practice is to set the condition to a boolean variable, with a good name for that variable. Another way is to move the long condition to a function.
Nested ifs, in which case the block should be placed
on the outermost if:
/* valid Linux kernel style */
if (condition) {
if (another_condition)
single_statement ();
else
another_single_statement ();
}
/* valid GNU style */
if (condition)
{
if (another_condition)
single_statement ();
else
another_single_statement ();
}
/* invalid */
if (condition)
if (another_condition)
single_statement ();
else if (yet_another_condition)
another_single_statement ();
En general, los bloques nuevos se deben colocar con un nivel de sangrado nuevo, como esto:
int retval = 0;
statement_1 ();
statement_2 ();
{
int var1 = 42;
gboolean res = FALSE;
res = statement_3 (var1);
retval = res ? -1 : 1;
}
While curly braces for function definitions should rest on a new line they should not add an indentation level:
/* valid Linux kernel style*/
static void
my_function (int argument)
{
do_my_things ();
}
/* valid GNU style*/
static void
my_function (int argument)
{
do_my_things ();
}
/* invalid */
static void
my_function (int argument) {
do_my_things ();
}
/* invalid */
static void
my_function (int argument)
{
do_my_things ();
}
Do not check boolean values for equality. By using implicit
comparisons, the resulting code can be read more like conversational
English. Another rationale is that a ‘true’ value may not be necessarily
equal to whatever the TRUE macro uses. For example:
/* invalid */
if (found == TRUE)
do_foo ();
/* invalid */
if (found == FALSE)
do_bar ();
/* valid */
if (found)
do_foo ();
/* valid */
if (!found)
do_bar ();
The C language uses the value 0 for many purposes. As a numeric value,
the end of a string, a null pointer and the FALSE boolean.
To make the code clearer, you should write code that highlights the
specific way 0 is used. So when reading a comparison, it is possible to
know the variable type. For boolean variables, an implicit comparison is
appropriate because it’s already a logical expression. Other variable
types are not logical expressions by themselves, so an explicit
comparison is better:
/* valid */
if (some_pointer == NULL)
do_blah ();
/* valid */
if (number == 0)
do_foo ();
/* valid */
if (str != NULL && *str != '\0')
do_bar ();
/* invalid */
if (!some_pointer)
do_blah ();
/* invalid */
if (!number)
do_foo ();
/* invalid */
if (str && *str)
do_bar ();
Las funciones se deben declarar colocando el valor devuelto en una línea separada del nombre de la función:
void
my_function (void)
{
…
}
The argument list must be broken into a new line for each argument, with the argument names right aligned, taking into account pointers:
void
my_function (some_type_t type,
another_type_t *a_pointer,
double_ptr_t **double_pointer,
final_type_t another_type)
{
…
}
If you use Emacs, you can use M-x align to do this
kind of alignment automatically. Just put the point and mark
around the function’s prototype, and invoke that command.
The alignment also holds when invoking a function without breaking the line length limit:
alinear_argumentos_funciones (primer_argumento,
segundo_argumento,
tercer_argumento);
Ponga siempre un espacio antes de abrir un paréntesis, pero nunca después:
/* valid */
if (condition)
do_my_things ();
/* valid */
switch (condition) {
}
/* invalid */
if(condition)
do_my_things();
/* invalid */
if ( condition )
do_my_things ( );
When declaring a structure type use newlines to separate logical sections of the structure:
struct _GtkWrapBoxPrivate
{
GtkOrientation orientation;
GtkWrapAllocationMode mode;
GtkWrapBoxSpreading horizontal_spreading;
GtkWrapBoxSpreading vertical_spreading;
guint16 vertical_spacing;
guint16 horizontal_spacing;
guint16 minimum_line_children;
guint16 natural_line_children;
GList *children;
};
No elimine espacios en blanco y saltos de línea simplemente porque algo quepa en una única línea:
/* invalid */
if (condition) foo (); else bar ();
Do eliminate trailing whitespace on any line, preferably as a separate patch or commit. Never use empty lines at the beginning or at the end of a file.
This is a little Emacs function that you can use to clean up lines with trailing whitespace:
(defun clean-line-ends ()
(interactive)
(if (not buffer-read-only)
(save-excursion
(goto-char (point-min))
(let ((count 0))
(while (re-search-forward "[ ]+$" nil t)
(setq count (+ count 1))
(replace-match "" t t))
(message "Cleaned %d lines" count)))))
A switch should open a block on a new
indentation level, and each case should start on
the same indentation level as the curly braces, with the case
block on a new indentation level:
/* valid Linux kernel style */
switch (condition) {
case FOO:
do_foo ();
break;
case BAR:
do_bar ();
break;
}
/* valid GNU style */
switch (condition)
{
case FOO:
do_foo ();
break;
case BAR:
do_bar ();
break;
}
/* invalid */
switch (condition) {
case FOO: do_foo (); break;
case BAR: do_bar (); break;
}
/* invalid */
switch (condition)
{
case FOO: do_foo ();
break;
case BAR: do_bar ();
break;
}
/* invalid */
switch (condition)
{
case FOO:
do_foo ();
break;
case BAR:
do_bar ();
break;
}
Es preferible, pero no obligatorio, separar los distintos casos con un salto de línea:
switch (condition) {
case FOO:
do_foo ();
break;
case BAR:
do_bar ();
break;
default:
do_default ();
}
La sentencia break para el caso default no es obligatoria.
If switching over an enumerated type, a case statement must
exist for every member of the enumerated type. For members you do not
want to handle, alias their case statements to
default:
switch (enumerated_condition) {
case HANDLED_1:
do_foo ();
break;
case HANDLED_2:
do_bar ();
break;
case IGNORED_1:
case IGNORED_2:
default:
do_default ();
}
If most members of the enumerated type should not be handled, consider
using an if statement instead of a switch.
If a case block needs to declare new variables, the same rules as the
inner blocks apply (see above); the break statement should be placed
outside of the inner block:
/* valid GNU style */
switch (condition)
{
case FOO:
{
int foo;
foo = do_foo ();
}
break;
…
}
The only major rule for headers is that the function definitions should be vertically aligned in three columns:
return_type function_name (type argument,
type argument,
type argument);
La anchura máxima de cada columna viene dada por el elemento más largo de la columna:
void gtk_type_set_property (GtkType *type,
const gchar *value,
GError **error);
const gchar *gtk_type_get_property (GtkType *type);
También es posible alinear las columnas al siguiente tabulador:
void gtk_type_set_prop (GtkType *type,
gfloat value);
gfloat gtk_type_get_prop (GtkType *type);
gint gtk_type_update_foobar (GtkType *type);
As before, you can use M-x align in Emacs to do
this automatically.
If you are creating a public library, try to export a single public header file that in turn includes all the smaller header files into it. This is so that public headers are never included directly; rather a single include is used in applications. For example, GTK+ uses the following in its header files that should not be included directly by applications:
#if !defined (__GTK_H_INSIDE__) && !defined (GTK_COMPILATION)
#error "Only <gtk/gtk.h> can be included directly."
#endif
For libraries, all headers should have inclusion guards (for
internal usage) and C++ guards. These provide the extern
"C" magic that C++ requires to include plain C headers:
#ifndef MYLIB_FOO_H_
#define MYLIB_FOO_H_
#include <gtk/gtk.h>
G_BEGIN_DECLS
…
G_END_DECLS
#endif /* MYLIB_FOO_H_ */
GObject class definitions and implementations require some additional coding style notices, and should always be correctly namespaced.
Las declaraciones «typedef» se deben colocar al principio del archivo.
typedef struct _GtkBoxedStruct GtkBoxedStruct;
typedef struct _GtkMoreBoxedStruct GtkMoreBoxedStruct;
Esto incluye los tipos enumerados:
typedef enum
{
GTK_SIZE_REQUEST_WIDTH_FOR_HEIGHT,
GTK_SIZE_REQUEST_HEIGHT_FOR_WIDTH
} GtkSizeRequestMode;
Y los tipos de retornos de llamadas:
typedef void (* GtkCallback) (GtkWidget *widget,
gpointer user_data);
Las instancias de estructuras se deben declarar usando G_DECLARE_FINAL_TYPE o G_DECLARE_DERIVABLE_TYPE:
#define GTK_TYPE_FOO (gtk_foo_get_type ())
G_DECLARE_FINAL_TYPE (GtkFoo, gtk_foo, GTK, FOO, GtkWidget)
For final types, private data can be stored in the object struct, which should be defined in the C file:
struct _GtkFoo
{
GObject parent_instance;
guint private_data;
gpointer more_private_data;
};
For derivable types, private data must be stored in a private struct in
the C file, configured using G_DEFINE_TYPE_WITH_PRIVATE()
and accessed using a _get_instance_private() function:
#define GTK_TYPE_FOO gtk_foo_get_type ()
G_DECLARE_DERIVABLE_TYPE (GtkFoo, gtk_foo, GTK, FOO, GtkWidget)
struct _GtkFooClass
{
GtkWidgetClass parent_class;
void (* handle_frob) (GtkFrobber *frobber,
guint n_frobs);
gpointer padding[12];
};
Always use the G_DEFINE_TYPE(),
G_DEFINE_TYPE_WITH_PRIVATE(), and
G_DEFINE_TYPE_WITH_CODE() macros, or their abstract variants
G_DEFINE_ABSTRACT_TYPE(),
G_DEFINE_ABSTRACT_TYPE_WITH_PRIVATE(),
and G_DEFINE_ABSTRACT_TYPE_WITH_CODE(); also, use the similar
macros for defining interfaces and boxed types.
Interface types should always have the dummy typedef for cast purposes:
typedef struct _GtkFooable GtkFooable;
The interface structure should have ‘Interface’ postfixed to the dummy typedef:
typedef struct _GtkFooableInterface GtkFooableInterface;
Las interfaces deben tener las siguientes macros:
Macro |
Se expande a |
|
|
|
|
|
|
|
|
When dynamically allocating data on the heap use g_new().
Public structure types should always be returned after being
zero-ed, either explicitly for each member, or by using
g_new0().
Consulte la para obtener más detalles.
Try to avoid private macros unless strictly necessary. Remember
to #undef them at the end of a block or a series of functions
needing them.
Normalmente, se prefieren las funciones en línea a las macros privadas
Public macros should not be used unless they evaluate to a constant.
Avoid exporting variables as public API, since this is cumbersome on some platforms. It is always preferable to add getters and setters instead. Also, beware global variables in general.
Non-exported functions that are needed in more than one source file
should be prefixed with an underscore (‘_’), and declared in a
private header file. For example, _mylib_internal_foo().
Las funciones con un guión bajo al principio nunca se exportan.
Non-exported functions that are only needed in one source file should be declared static.