coding-style.rst

   1.. include:: ../disclaimer-sp.rst
   2
   3:Original: :ref:`Documentation/process/coding-style.rst <submittingpatches>`
   4:Translator: Carlos Bilbao <carlos.bilbao.osdev@gmail.com>
   5
   6.. _sp_codingstyle:
   7
   8Estilo en el código del kernel Linux
   9=====================================
  10
  11Este es un breve documento que describe el estilo preferido en el código
  12del kernel Linux. El estilo de código es muy personal y no **forzaré** mi
  13puntos de vista sobre nadie, pero esto vale para todo lo que tengo que
  14mantener, y preferiría que para la mayoría de otras cosas también. Por
  15favor, por lo menos considere los argumentos expuestos aquí.
  16
  17En primer lugar, sugeriría imprimir una copia de los estándares de código
  18GNU, y NO leerlo. Quémelos, es un gran gesto simbólico.
  19
  20De todos modos, aquí va:
  21
  22
  231) Sangría
  24-----------
  25
  26Las tabulaciones tienen 8 caracteres y, por lo tanto, las sangrías también
  27tienen 8 caracteres. Hay movimientos heréticos que intentan hacer sangría
  28de 4 (¡o incluso 2!) caracteres de longitud, y eso es similar a tratar de
  29definir el valor de PI como 3.
  30
  31Justificación: La idea detrás de la sangría es definir claramente dónde
  32comienza y termina un bloque de control. Especialmente, cuando ha estado
  33buscando en su pantalla durante 20 horas seguidas, le resultará mucho más
  34fácil ver cómo funciona la sangría si tiene sangrías grandes.
  35
  36Bueno, algunas personas dirán que tener sangrías de 8 caracteres hace que
  37el código se mueva demasiado a la derecha y dificulta la lectura en una
  38pantalla de terminal de 80 caracteres. La respuesta a eso es que si
  39necesita más de 3 niveles de sangría, está en apuros de todos modos y
  40debería arreglar su programa.
  41
  42En resumen, las sangrías de 8 caracteres facilitan la lectura y tienen la
  43ventaja añadida de advertirle cuando está anidando sus funciones demasiado
  44profundo. Preste atención a esa advertencia.
  45
  46La forma preferida de facilitar múltiples niveles de sangría en una
  47declaración de switch es para alinear el ``switch`` y sus etiquetas
  48``case`` subordinadas en la misma columna, en lugar de hacer ``doble
  49sangría`` (``double-indenting``) en etiquetas ``case``. Por ejemplo:
  50
  51.. code-block:: c
  52
  53	switch (suffix) {
  54	case 'G':
  55	case 'g':
  56		mem <<= 30;
  57		break;
  58	case 'M':
  59	case 'm':
  60		mem <<= 20;
  61		break;
  62	case 'K':
  63	case 'k':
  64		mem <<= 10;
  65		fallthrough;
  66	default:
  67		break;
  68	}
  69
  70No ponga varias declaraciones en una sola línea a menos que tenga algo que
  71ocultar:
  72
  73.. code-block:: c
  74
  75	if (condición) haz_esto;
  76	  haz_otra_cosa;
  77
  78No use comas para evitar el uso de llaves:
  79
  80.. code-block:: c
  81
  82	if (condición)
  83		haz_esto(), haz_eso();
  84
  85Siempre use llaves para múltiples declaraciones:
  86
  87.. code-block:: c
  88
  89	if (condición) {
  90		haz_esto();
  91		haz_eso();
  92	}
  93
  94Tampoco ponga varias asignaciones en una sola línea. El estilo de código
  95del kernel es súper simple. Evite las expresiones engañosas.
  96
  97
  98Aparte de los comentarios, la documentación y excepto en Kconfig, los
  99espacios nunca se utilizan para la sangría, y el ejemplo anterior se rompe
 100deliberadamente.
 101
 102Consiga un editor decente y no deje espacios en blanco al final de las
 103líneas.
 104
 1052) Rompiendo líneas y strings largos
 106------------------------------------
 107
 108El estilo de código tiene todo que ver con la legibilidad y la
 109mantenibilidad usando herramientas disponibles comúnmente.
 110
 111El límite preferido en la longitud de una sola línea es de 80 columnas.
 112
 113Las declaraciones de más de 80 columnas deben dividirse en partes, a menos
 114que exceder las 80 columnas aumente significativamente la legibilidad y no
 115oculte información.
 116
 117Los descendientes siempre son sustancialmente más cortos que el padre y
 118se colocan sustancialmente a la derecha. Un estilo muy usado es alinear
 119descendientes a un paréntesis de función abierto.
 120
 121Estas mismas reglas se aplican a los encabezados de funciones con una larga
 122lista de argumentos.
 123
 124Sin embargo, nunca rompa los strings visibles para el usuario, como los
 125mensajes printk, porque eso rompe la capacidad de grep a estos.
 126
 127
 1283) Colocación de llaves y espacios
 129----------------------------------
 130
 131El otro problema que siempre surge en el estilo C es la colocación de
 132llaves. A diferencia del tamaño de la sangría, existen pocas razones
 133técnicas para elegir una estrategia de ubicación sobre la otra, pero la
 134forma preferida, como mostraron los profetas Kernighan y Ritchie, es poner
 135la llave de apertura en la línea, y colocar la llave de cierre primero,
 136así:
 137
 138.. code-block:: c
 139
 140	if (x es verdad) {
 141		hacemos y
 142	}
 143
 144Esto se aplica a todos los bloques de declaraciones que no son funciones
 145(if, switch, for, while, do). Por ejemplo:
 146
 147.. code-block:: c
 148
 149	switch (action) {
 150	case KOBJ_ADD:
 151		return "add";
 152	case KOBJ_REMOVE:
 153		return "remove";
 154	case KOBJ_CHANGE:
 155		return "change";
 156	default:
 157		return NULL;
 158	}
 159
 160Sin embargo, hay un caso especial, a saber, las funciones: tienen la llave
 161de apertura al comienzo de la siguiente línea, así:
 162
 163.. code-block:: c
 164
 165	int funcion(int x)
 166	{
 167		cuerpo de la función
 168	}
 169
 170Gente hereje de todo el mundo ha afirmado que esta inconsistencia es...
 171bueno... inconsistente, pero todas las personas sensatas saben que
 172(a) K&R tienen **razón** y (b) K&R tienen razón. Además, las funciones son
 173especiales de todos modos (no puede anidarlas en C).
 174
 175Tenga en cuenta que la llave de cierre está vacía en su línea propia,
 176**excepto** en los casos en que es seguida por una continuación de la misma
 177declaración, es decir, un ``while`` en una sentencia do o un ``else`` en
 178una sentencia if, como en:
 179
 180.. code-block:: c
 181
 182	do {
 183		cuerpo del bucle do
 184	} while (condition);
 185
 186y
 187
 188.. code-block:: c
 189
 190	if (x == y) {
 191		..
 192	} else if (x > y) {
 193		...
 194	} else {
 195		....
 196	}
 197
 198Justificación: K&R.
 199
 200Además, tenga en cuenta que esta colocación de llaves también minimiza el
 201número de líneas vacías (o casi vacías), sin pérdida de legibilidad. Así,
 202como el suministro de nuevas líneas en su pantalla no es un recurso
 203renovable (piense en pantallas de terminal de 25 líneas), tienes más líneas
 204vacías para poner comentarios.
 205
 206No use llaves innecesariamente donde una sola declaración sea suficiente.
 207
 208.. code-block:: c
 209
 210	if (condition)
 211		accion();
 212
 213y
 214
 215.. code-block:: none
 216
 217	if (condición)
 218		haz_esto();
 219	else
 220		haz_eso();
 221
 222Esto no aplica si solo una rama de una declaración condicional es una sola
 223declaración; en este último caso utilice llaves en ambas ramas:
 224
 225.. code-block:: c
 226
 227	if (condición) {
 228		haz_esto();
 229		haz_eso();
 230	} else {
 231		en_otro_caso();
 232	}
 233
 234Además, use llaves cuando un bucle contenga más de una declaración simple:
 235
 236.. code-block:: c
 237
 238	while (condición) {
 239		if (test)
 240			haz_eso();
 241	}
 242
 2433.1) Espacios
 244*************
 245
 246El estilo del kernel Linux para el uso de espacios depende (principalmente)
 247del uso de función versus uso de palabra clave. Utilice un espacio después
 248de (la mayoría de) las palabras clave. Las excepciones notables son sizeof,
 249typeof, alignof y __attribute__, que parecen algo así como funciones (y
 250generalmente se usan con paréntesis en Linux, aunque no son requeridos en
 251el idioma, como en: ``sizeof info`` después de que ``struct fileinfo info;``
 252se declare).
 253
 254Así que use un espacio después de estas palabras clave::
 255
 256	if, switch, case, for, do, while
 257
 258pero no con sizeof, typeof, alignof, o __attribute__. Por ejemplo,
 259
 260.. code-block:: c
 261
 262
 263	s = sizeof(struct file);
 264
 265No agregue espacios alrededor (dentro) de expresiones entre paréntesis.
 266Este ejemplo es **malo**:
 267
 268.. code-block:: c
 269
 270
 271	s = sizeof( struct file );
 272
 273Al declarar datos de puntero o una función que devuelve un tipo de puntero,
 274el uso preferido de ``*`` es adyacente al nombre del dato o nombre de la
 275función y no junto al nombre del tipo. Ejemplos:
 276
 277.. code-block:: c
 278
 279
 280	char *linux_banner;
 281	unsigned long long memparse(char *ptr, char **retptr);
 282	char *match_strdup(substring_t *s);
 283
 284Use un espacio alrededor (a cada lado de) la mayoría de los operadores
 285binarios y ternarios, como cualquiera de estos::
 286
 287	=  +  -  <  >  *  /  %  |  &  ^  <=  >=  ==  !=  ?  :
 288
 289pero sin espacio después de los operadores unarios::
 290
 291	&  *  +  -  ~  !  sizeof  typeof  alignof  __attribute__  defined
 292
 293sin espacio antes de los operadores unarios de incremento y decremento del
 294sufijo::
 295
 296	++  --
 297
 298y sin espacio alrededor de los operadores de miembros de estructura ``.`` y
 299``->``.
 300
 301No deje espacios en blanco al final de las líneas. Algunos editores con
 302``inteligente`` sangría insertarán espacios en blanco al comienzo de las
 303nuevas líneas como sea apropiado, para que pueda comenzar a escribir la
 304siguiente línea de código de inmediato. Sin embargo, algunos de estos
 305editores no eliminan los espacios en blanco si finalmente no termina
 306poniendo una línea de código allí, como si dejara una línea en blanco. Como
 307resultado, termina con líneas que contienen espacios en blanco al final.
 308
 309Git le advertirá sobre los parches que introducen espacios en blanco al
 310final y puede, opcionalmente, eliminar los espacios en blanco finales por
 311usted; sin embargo, si se aplica una serie de parches, esto puede hacer que
 312los parches posteriores de la serie fallen al cambiar sus líneas de
 313contexto.
 314
 315
 3164) Nomenclatura
 317---------------
 318
 319C es un lenguaje espartano, y sus convenciones de nomenclatura deberían
 320seguir su ejemplo. A diferencia de los programadores de Modula-2 y Pascal,
 321los programadores de C no usan nombres cuquis como
 322EstaVariableEsUnContadorTemporal. Un programador de C lo llamaría
 323variable ``tmp``, que es mucho más fácil de escribir, y no es mas difícil
 324de comprender.
 325
 326SIN EMBARGO, mientras que los nombres de mayúsculas y minúsculas están mal
 327vistos, los nombres descriptivos para las variables globales son
 328imprescindibles. Llamar a una función global ``foo`` es un delito.
 329
 330Una variable GLOBAL (para usar solo si **realmente** las necesita) necesita
 331tener un nombre descriptivo, al igual que las funciones globales. Si tiene
 332una función que cuenta el número de usuarios activos, debe llamar a esta
 333``contar_usuarios_activos()`` o similar, **no** debe llamarlo ``cntusr()``.
 334
 335Codificar el tipo de una función en el nombre (lo llamado notación húngara)
 336es estúpido: el compilador conoce los tipos de todos modos y puede
 337verificar estos, y solo confunde al programador.
 338
 339Los nombres de las variables LOCALES deben ser breves y directos. Si usted
 340tiene algún contador aleatorio de tipo entero, probablemente debería
 341llamarse ``i``. Llamarlo ``loop_counter`` no es productivo, si no hay
 342posibilidad de ser mal entendido. De manera similar, ``tmp`` puede ser casi
 343cualquier tipo de variable que se utiliza para contener un valor temporal.
 344
 345Si tiene miedo de mezclar los nombres de las variables locales, tiene otro
 346problema, que se denomina síndrome de
 347función-crecimiento-desequilibrio-de-hormona. Vea el capítulo 6 (Funciones).
 348
 349Para nombres de símbolos y documentación, evite introducir nuevos usos de
 350'master / slave' (maestro / esclavo) (o 'slave' independientemente de
 351'master') y 'lista negra / lista blanca' (backlist / whitelist).
 352
 353Los reemplazos recomendados para 'maestro / esclavo' son:
 354    '{primary,main} / {secondary,replica,subordinate}'
 355    '{initiator,requester} / {target,responder}'
 356    '{controller,host} / {device,worker,proxy}'
 357    'leader / follower'
 358    'director / performer'
 359
 360Los reemplazos recomendados para 'backlist / whitelist' son:
 361    'denylist / allowlist'
 362    'blocklist / passlist'
 363
 364Las excepciones para la introducción de nuevos usos son mantener en espacio
 365de usuario una ABI/API, o al actualizar la especificación del código de un
 366hardware o protocolo existente (a partir de 2020) que requiere esos
 367términos. Para nuevas especificaciones, traduzca el uso de la terminología
 368de la especificación al estándar de código del kernel donde sea posible.
 369
 3705) Typedefs
 371-----------
 372
 373Por favor no use cosas como ``vps_t``.
 374Es un **error** usar typedef para estructuras y punteros. cuando ve un
 375
 376.. code-block:: c
 377
 378
 379	vps_t a;
 380
 381en el código fuente, ¿qué significa?
 382En cambio, si dice
 383
 384.. code-block:: c
 385
 386	struct virtual_container *a;
 387
 388puede decir qué es ``a`` en realidad.
 389
 390Mucha gente piensa que  los typedefs ``ayudan a la legibilidad``. No. Son
 391útiles solamente para:
 392
 393 (a) objetos totalmente opacos (donde el typedef se usa activamente para
 394     **ocultar** cuál es el objeto).
 395
 396     Ejemplo: ``pte_t`` etc. objetos opacos a los que solo puede acceder
 397     usando las funciones de acceso adecuadas.
 398
 399     .. note::
 400
 401       La opacidad y las ``funciones de acceso`` no son buenas por sí
 402       mismas. La razón por la que los tenemos para cosas como pte_t, etc.
 403       es que hay real y absolutamente **cero** información accesible de
 404       forma portátil allí.
 405
 406 (b) Tipos enteros claros, donde la abstracción **ayuda** a evitar
 407     confusiones, ya sea ``int`` o ``long``.
 408
 409     u8/u16/u32 son definiciones tipográficas perfectamente correctas
 410     aunque encajan en la categoría (d) mejor que aquí.
 411
 412     .. note::
 413
 414       De nuevo - debe haber una **razón** para esto. si algo es
 415       ``unsigned long``, entonces no hay razón para hacerlo
 416
 417	typedef unsigned long mis_flags_t;
 418
 419     pero si hay una razón clara de por qué bajo ciertas circunstancias
 420     podría ser un ``unsigned int`` y bajo otras configuraciones podría
 421     ser ``unsigned long``, entonces, sin duda, adelante y use un typedef.
 422
 423 (c) cuando lo use para crear literalmente un tipo **nuevo** para
 424     comprobación de tipos.
 425
 426 (d) Nuevos tipos que son idénticos a los tipos estándar C99, en ciertas
 427     circunstancias excepcionales.
 428
 429     Aunque sólo costaría un corto período de tiempo para los ojos y
 430     cerebro para acostumbrarse a los tipos estándar como ``uint32_t``,
 431     algunas personas se oponen a su uso de todos modos.
 432
 433     Por lo tanto, los tipos ``u8/u16/u32/u64`` específicos de Linux y sus
 434     equivalentes con signo, que son idénticos a los tipos estándar son
 435     permitidos, aunque no son obligatorios en el nuevo código de su
 436     elección.
 437
 438     Al editar código existente que ya usa uno u otro conjunto de tipos,
 439     debe ajustarse a las opciones existentes en ese código.
 440
 441 (e) Tipos seguros para usar en el espacio de usuario.
 442
 443     En ciertas estructuras que son visibles para el espacio de usuario, no
 444     podemos requerir tipos C99 y o utilizat el ``u32`` anterior. Por lo
 445     tanto, usamos __u32 y tipos similares en todas las estructuras que se
 446     comparten con espacio de usuario.
 447
 448Tal vez también haya otros casos, pero la regla básicamente debería ser
 449NUNCA JAMÁS use un typedef a menos que pueda coincidir claramente con una
 450de estas reglas.
 451
 452En general, un puntero o una estructura que tiene elementos que pueden
 453ser razonablemente accedidos directamente, **nunca** deben ser un typedef.
 454
 4556) Funciones
 456------------
 457
 458Las funciones deben ser cortas y dulces, y hacer una sola cosa. Deberían
 459caber en una o dos pantallas de texto (el tamaño de pantalla ISO/ANSI es
 46080x24, como todos sabemos), y hacer una cosa y hacerla bien.
 461
 462La longitud máxima de una función es inversamente proporcional a la
 463complejidad y el nivel de sangría de esa función. Entonces, si tiene una
 464función conceptualmente simple que es solo una larga (pero simple)
 465declaración de case, donde tiene que hacer un montón de pequeñas cosas para
 466un montón de diferentes casos, está bien tener una función más larga.
 467
 468Sin embargo, si tiene una función compleja y sospecha que un estudiante de
 469primer año de secundaria menos que dotado podría no comprender de qué se
 470trata la función, debe adherirse a los límites máximos tanto más de
 471cerca. Use funciones auxiliares con nombres descriptivos (puede pedirle al
 472compilador que los alinee si cree que es crítico para el rendimiento, y
 473probablemente lo hará mejor de lo que usted hubiera hecho).
 474
 475Otra medida de la función es el número de variables locales. Estas no deben
 476exceder de 5 a 10, o está haciendo algo mal. Piense de nuevo en la función
 477y divida en partes más pequeñas. Un cerebro humano puede generalmente
 478realiza un seguimiento de aproximadamente 7 cosas diferentes, cualquier
 479elemento más y se confunde. Usted sabe que es brillante, pero tal vez le
 480gustaría entender lo que hizo dentro de 2 semanas.
 481
 482En los archivos fuente, separe las funciones con una línea en blanco. Si la
 483función es exportada, la macro **EXPORT** debería ponerse inmediatamente
 484después de la función de cierre de línea de llave. Por ejemplo:
 485
 486.. code-block:: c
 487
 488	int sistema_corriendo(void)
 489	{
 490		return estado_sistema == SISTEMA_CORRIENDO;
 491	}
 492	EXPORT_SYMBOL(sistema_corriendo);
 493
 4946.1) Prototipos de funciones
 495****************************
 496
 497En los prototipos de funciones, incluya nombres de parámetros con sus tipos
 498de datos. Aunque esto no es requerido por el lenguaje C, se prefiere en
 499Linux porque es una forma sencilla de añadir información valiosa para el
 500lector.
 501
 502No utilice la palabra clave ``extern`` con declaraciones de función ya que
 503esto hace las líneas más largas y no es estrictamente necesario.
 504
 505Al escribir prototipos de funciones, mantenga el `orden de los elementos regular
 506<https://lore.kernel.org/mm-commits/CAHk-=wiOCLRny5aifWNhr621kYrJwhfURsa0vFPeUEm8mF0ufg@mail.gmail.com/>`_.
 507Por ejemplo, usando este ejemplo de declaración de función::
 508
 509 __init void * __must_check action(enum magic value, size_t size, u8 count,
 510				   char *fmt, ...) __printf(4, 5) __malloc;
 511
 512El orden preferido de elementos para un prototipo de función es:
 513
 514- clase de almacenamiento (a continuación, ``static __always_inline``,
 515  teniendo en cuenta que ``__always_inline`` es técnicamente un atributo
 516  pero se trata como ``inline``)
 517- atributos de clase de almacenamiento (aquí, ``__init`` -- es decir,
 518  declaraciones de sección, pero también cosas como ``__cold``)
 519- tipo de retorno (aquí, ``void *``)
 520- atributos de tipo de retorno (aquí, ``__must_check``)
 521- nombre de la función (aquí, ``action``)
 522- parámetros de la función (aquí, ``(enum magic value, size_t size, u8 count, char *fmt, ...)``,
 523  teniendo en cuenta que los nombres de los parámetros siempre deben
 524  incluirse)
 525- atributos de parámetros de función (aquí, ``__printf(4, 5)``)
 526- atributos de comportamiento de la función (aquí, ``__malloc``)
 527
 528Tenga en cuenta que para una **definición** de función (es decir, el cuerpo
 529real de la función), el compilador no permite atributos de parámetros de
 530función después de parámetros de la función. En estos casos, deberán ir
 531tras los atributos de clase (por ejemplo, tenga en cuenta el cambio de
 532posición de ``__printf(4, 5)`` a continuación, en comparación con el
 533ejemplo de **declaración** anterior)::
 534
 535 static __always_inline __init __printf(4, 5) void * __must_check action(enum magic value,
 536		size_t size, u8 count, char *fmt, ...) __malloc
 537 {
 538	...
 539 }
 540
 5417) Salida centralizada de funciones
 542-----------------------------------
 543
 544Aunque desaprobado por algunas personas, el equivalente de la instrucción
 545goto es utilizado con frecuencia por los compiladores, en forma de
 546instrucción de salto incondicional.
 547
 548La declaración goto es útil cuando una función sale desde múltiples
 549ubicaciones y se deben realizar algunos trabajos comunes, como la limpieza.
 550Si no se necesita limpieza, entonces simplemente haga return directamente.
 551
 552Elija nombres de etiquetas que digan qué hace el goto o por qué existe el
 553goto. Un ejemplo de un buen nombre podría ser ``out_free_buffer:``
 554(``salida_liberar_buffer``) si al irse libera ``buffer``. Evite usar
 555nombres GW-BASIC como ``err1:`` y ``err2:``, ya que tendría que volver a
 556numerarlos si alguna vez agrega o elimina rutas de salida, y hacen que sea
 557difícil de verificar que sean correctos, de todos modos.
 558
 559La razón para usar gotos es:
 560
 561- Las declaraciones incondicionales son más fáciles de entender y seguir.
 562- se reduce el anidamiento
 563- errores al no actualizar los puntos de salida individuales al hacer
 564  modificaciones son evitados
 565- ahorra el trabajo del compilador de optimizar código redundante ;)
 566
 567.. code-block:: c
 568
 569	int fun(int a)
 570	{
 571		int result = 0;
 572		char *buffer;
 573
 574		buffer = kmalloc(SIZE, GFP_KERNEL);
 575		if (!buffer)
 576			return -ENOMEM;
 577
 578		if (condition1) {
 579			while (loop1) {
 580				...
 581			}
 582			result = 1;
 583			goto out_free_buffer;
 584		}
 585		...
 586	out_free_buffer:
 587		kfree(buffer);
 588		return result;
 589	}
 590
 591Un tipo común de error a tener en cuenta es "un error de error" que es algo
 592así:
 593
 594.. code-block:: c
 595
 596	err:
 597		kfree(foo->bar);
 598		kfree(foo);
 599		return ret;
 600
 601El error en este código es que en algunas rutas de salida, ``foo`` es NULL.
 602Normalmente la solución para esto es dividirlo en dos etiquetas de error
 603``err_free_bar:`` y ``err_free_foo:``:
 604
 605.. code-block:: c
 606
 607	err_free_bar:
 608		kfree(foo->bar);
 609	err_free_foo:
 610		kfree(foo);
 611		return ret;
 612
 613Idealmente, debería simular errores para probar todas las rutas de salida.
 614
 615
 6168) Comentarios
 617--------------
 618
 619Los comentarios son buenos, pero también existe el peligro de comentar
 620demasiado. NUNCA trate de explicar CÓMO funciona su código en un
 621comentario: es mucho mejor escribir el código para que el
 622**funcionamiento** sea obvio y es una pérdida de tiempo explicar código mal
 623escrito.
 624
 625Generalmente, desea que sus comentarios digan QUÉ hace su código, no CÓMO.
 626Además, trate de evitar poner comentarios dentro del cuerpo de una función:
 627si la función es tan compleja que necesita comentar por separado partes de
 628esta, probablemente debería volver al capítulo 6 una temporada. Puede
 629hacer pequeños comentarios para notar o advertir sobre algo particularmente
 630inteligente (o feo), pero trate de evitar el exceso. En su lugar, ponga los
 631comentarios al principio de la función, diga a la gente lo que hace y
 632posiblemente POR QUÉ hace esto.
 633
 634Al comentar las funciones de la API del kernel, utilice el formato
 635kernel-doc. Consulte los archivos en :ref:`Documentation/doc-guide/ <doc_guide>`
 636y ``scripts/kernel-doc`` para más detalles.
 637
 638El estilo preferido para comentarios largos (de varias líneas) es:
 639
 640.. code-block:: c
 641
 642	/*
 643	* Este es el estilo preferido para comentarios
 644	* multilínea en el código fuente del kernel Linux.
 645	* Por favor, utilícelo constantemente.
 646	*
 647	* Descripción: Una columna de asteriscos en el lado izquierdo,
 648	* con líneas iniciales y finales casi en blanco.
 649	*/
 650
 651Para archivos en net/ y drivers/net/, el estilo preferido para comentarios
 652largos (multi-linea) es un poco diferente.
 653
 654.. code-block:: c
 655
 656	/* El estilo de comentario preferido para archivos en net/ y drivers/net
 657	* se asemeja a esto.
 658	*
 659	* Es casi lo mismo que el estilo de comentario generalmente preferido,
 660	* pero no hay una línea inicial casi en blanco.
 661	*/
 662
 663También es importante comentar los datos, ya sean tipos básicos o
 664derivados. Para este fin, use solo una declaración de datos por línea (sin
 665comas para múltiples declaraciones de datos). Esto le deja espacio para un
 666pequeño comentario sobre cada elemento, explicando su uso.
 667
 6689) Has hecho un desastre
 669---------------------------
 670
 671Está bien, todos lo hacemos. Probablemente un antiguo usuario de Unix le
 672haya dicho que ``GNU emacs`` formatea automáticamente las fuentes C por
 673usted, y ha notado que sí, lo hace, pero los por defecto que tiene son
 674menos que deseables (de hecho, son peores que los aleatorios) escribiendo -
 675un número infinito de monos escribiendo en GNU emacs nunca harán un buen
 676programa).
 677
 678Por lo tanto, puede deshacerse de GNU emacs o cambiarlo y usar valores más
 679sanos. Para hacer esto último, puede pegar lo siguiente en su archivo
 680.emacs:
 681
 682.. code-block:: none
 683
 684  (defun c-lineup-arglist-tabs-only (ignored)
 685    "Line up argument lists by tabs, not spaces"
 686    (let* ((anchor (c-langelem-pos c-syntactic-element))
 687           (column (c-langelem-2nd-pos c-syntactic-element))
 688           (offset (- (1+ column) anchor))
 689           (steps (floor offset c-basic-offset)))
 690      (* (max steps 1)
 691         c-basic-offset)))
 692
 693  (dir-locals-set-class-variables
 694   'linux-kernel
 695   '((c-mode . (
 696          (c-basic-offset . 8)
 697          (c-label-minimum-indentation . 0)
 698          (c-offsets-alist . (
 699                  (arglist-close         . c-lineup-arglist-tabs-only)
 700                  (arglist-cont-nonempty .
 701                      (c-lineup-gcc-asm-reg c-lineup-arglist-tabs-only))
 702                  (arglist-intro         . +)
 703                  (brace-list-intro      . +)
 704                  (c                     . c-lineup-C-comments)
 705                  (case-label            . 0)
 706                  (comment-intro         . c-lineup-comment)
 707                  (cpp-define-intro      . +)
 708                  (cpp-macro             . -1000)
 709                  (cpp-macro-cont        . +)
 710                  (defun-block-intro     . +)
 711                  (else-clause           . 0)
 712                  (func-decl-cont        . +)
 713                  (inclass               . +)
 714                  (inher-cont            . c-lineup-multi-inher)
 715                  (knr-argdecl-intro     . 0)
 716                  (label                 . -1000)
 717                  (statement             . 0)
 718                  (statement-block-intro . +)
 719                  (statement-case-intro  . +)
 720                  (statement-cont        . +)
 721                  (substatement          . +)
 722                  ))
 723          (indent-tabs-mode . t)
 724          (show-trailing-whitespace . t)
 725          ))))
 726
 727  (dir-locals-set-directory-class
 728   (expand-file-name "~/src/linux-trees")
 729   'linux-kernel)
 730
 731Esto hará que emacs funcione mejor con el estilo de código del kernel para
 732C en archivos bajo ``~/src/linux-trees``.
 733
 734Pero incluso si no logra que emacs realice un formateo correcto, no todo
 735está perdido: use ``indent``.
 736
 737Ahora bien, de nuevo, la sangría de GNU tiene la misma configuración de
 738muerte cerebral que GNU emacs tiene, por lo que necesita darle algunas
 739opciones de línea de comando. Sin embargo, eso no es tan malo, porque
 740incluso los creadores de GNU indent reconocen la autoridad de K&R (la gente
 741de GNU no es mala, solo están gravemente equivocados en este asunto), por
 742lo que simplemente de a la sangría las opciones ``-kr -i8`` (significa
 743``K&R, guiones de 8 caracteres``), o use ``scripts/Lindent``, que indenta
 744con ese estilo.
 745
 746``indent`` tiene muchas opciones, y especialmente cuando se trata de
 747comentar reformateos, es posible que desee echar un vistazo a la página del
 748manual. Pero recuerde: ``indent`` no es la solución para una mala
 749programación.
 750
 751Tenga en cuenta que también puede usar la herramienta ``clang-format`` para
 752ayudarlo con estas reglas, para volver a formatear rápidamente partes de su
 753código automáticamente, y revisar archivos completos para detectar errores
 754de estilo del código, errores tipográficos y posibles mejoras. También es
 755útil para ordenar ``#includes``, para alinear variables/macros, para
 756redistribuir texto y otras tareas similares. Vea el archivo
 757:ref:`Documentation/dev-tools/clang-format.rst <clangformat>` para más
 758detalles.
 759
 76010) Archivos de configuración de Kconfig
 761----------------------------------------
 762
 763Para todos los archivos de configuración de Kconfig* en todo el árbol
 764fuente, la sangría es algo diferente. Las líneas bajo una definición
 765``config`` están indentadas con una tabulación, mientras que el texto de
 766ayuda tiene una sangría adicional de dos espacios. Ejemplo::
 767
 768  config AUDIT
 769	bool "Soporte para auditar"
 770	depends on NET
 771	help
 772	  Habilita la infraestructura de auditoría que se puede usar con otro
 773	  subsistema kernel, como SELinux (que requiere esto para
 774	  registro de salida de mensajes avc). No hace auditoría de llamadas al
 775    sistema sin CONFIG_AUDITSYSCALL.
 776
 777Características seriamente peligrosas (como soporte de escritura para
 778ciertos filesystems) deben anunciar esto de forma destacada en su cadena de
 779solicitud::
 780
 781  config ADFS_FS_RW
 782	bool "ADFS write support (DANGEROUS)"
 783	depends on ADFS_FS
 784	...
 785
 786Para obtener la documentación completa sobre los archivos de configuración,
 787consulte el archivo Documentation/kbuild/kconfig-language.rst.
 788
 789
 79011) Estructuras de datos
 791------------------------
 792
 793Las estructuras de datos que tienen visibilidad fuera del contexto de un
 794solo subproceso en el que son creadas y destruidas, siempre debe tener
 795contadores de referencia. En el kernel, la recolección de basura no existe
 796(y fuera, la recolección de basura del kernel es lenta e ineficiente), lo
 797que significa que absolutamente **tiene** para hacer referencia y contar
 798todos sus usos.
 799
 800El conteo de referencias significa que puede evitar el bloqueo y permite
 801que múltiples usuarios tengan acceso a la estructura de datos en paralelo -
 802y no tengan que preocuparse de que la estructura, de repente, desaparezca
 803debajo de su control, solo porque durmieron o hicieron otra cosa por un
 804tiempo.
 805
 806Tenga en cuenta que el bloqueo **no** reemplaza el recuento de referencia.
 807El bloqueo se utiliza para mantener la coherencia de las estructuras de
 808datos, mientras que la referencia y contar es una técnica de gestión de
 809memoria. Por lo general, ambos son necesarios, y no deben confundirse entre
 810sí.
 811
 812De hecho, muchas estructuras de datos pueden tener dos niveles de conteo de
 813referencias, cuando hay usuarios de diferentes ``clases``. El conteo de
 814subclases cuenta el número de usuarios de la subclase y disminuye el conteo
 815global solo una vez, cuando el recuento de subclases llega a cero.
 816
 817Se pueden encontrar ejemplos de este tipo de ``recuento de referencias de
 818niveles múltiples`` en la gestión de memoria (``struct mm_struct``:
 819mm_users y mm_count), y en código del sistema de archivos
 820(``struct super_block``: s_count y s_active).
 821
 822Recuerde: si otro hilo puede encontrar su estructura de datos y usted no
 823tiene un recuento de referencias, es casi seguro que tiene un error.
 824
 82512) Macros, Enums y RTL
 826------------------------
 827
 828Los nombres de macros que definen constantes y etiquetas en enumeraciones
 829(enums) están en mayúsculas.
 830
 831.. code-block:: c
 832
 833	#define CONSTANTE 0x12345
 834
 835Se prefieren los enums cuando se definen varias constantes relacionadas.
 836
 837Se aprecian los nombres de macro en MAYÚSCULAS, pero las macros que se
 838asemejan a funciones puede ser nombradas en minúscula.
 839
 840Generalmente, las funciones en línea son preferibles a las macros que se
 841asemejan a funciones.
 842
 843Las macros con varias instrucciones deben contenerse en un bloque do-while:
 844
 845.. code-block:: c
 846
 847	#define macrofun(a, b, c)			\
 848		do {					\
 849			if (a == 5)			\
 850				haz_esto(b, c);		\
 851		} while (0)
 852
 853Cosas a evitar al usar macros:
 854
 8551) macros que afectan el flujo de control:
 856
 857.. code-block:: c
 858
 859	#define FOO(x)					\
 860		do {					\
 861			if (blah(x) < 0)		\
 862				return -EBUGGERED;	\
 863		} while (0)
 864
 865es una **muy** mala idea. Parece una llamada de función pero sale de la
 866función de ``llamada``; no rompa los analizadores internos de aquellos que
 867leerán el código.
 868
 8692) macros que dependen de tener una variable local con un nombre mágico:
 870
 871.. code-block:: c
 872
 873	#define FOO(val) bar(index, val)
 874
 875puede parecer algo bueno, pero es confuso como el infierno cuando uno lee
 876el código, y es propenso a romperse por cambios aparentemente inocentes.
 877
 8783) macros con argumentos que se usan como valores l: FOO(x) = y; le van
 879a morder si alguien, por ejemplo, convierte FOO en una función en línea.
 880
 8814) olvidarse de la precedencia: las macros que definen constantes usando
 882expresiones deben encerrar la expresión entre paréntesis. Tenga cuidado con
 883problemas similares con macros usando parámetros.
 884
 885.. code-block:: c
 886
 887	#define CONSTANTE 0x4000
 888	#define CONSTEXP (CONSTANTE | 3)
 889
 8905) colisiones de espacio de nombres ("namespace") al definir variables
 891locales en macros que se asemejan a funciones:
 892
 893.. code-block:: c
 894
 895	#define FOO(x)				\
 896	({					\
 897		typeof(x) ret;			\
 898		ret = calc_ret(x);		\
 899		(ret);				\
 900	})
 901
 902ret es un nombre común para una variable local -es menos probable que
 903__foo_ret colisione (coincida) con una variable existente.
 904
 905El manual de cpp trata las macros de forma exhaustiva. El manual interno de
 906gcc también cubre RTL, que se usa frecuentemente con lenguaje ensamblador
 907en el kernel.
 908
 90913) Imprimir mensajes del kernel
 910--------------------------------
 911
 912A los desarrolladores del kernel les gusta ser vistos como alfabetizados.
 913Cuide la ortografía de los mensajes del kernel para causar una buena
 914impresión. No utilice contracciones incorrectas como ``dont``; use
 915``do not`` o ``don't`` en su lugar. Haga sus mensajes concisos, claros e
 916inequívocos.
 917
 918Los mensajes del kernel no tienen que terminar con un punto.
 919
 920Imprimir números entre paréntesis (%d) no agrega valor y debe evitarse.
 921
 922Hay varias modelos de macros de diagnóstico de driver en <linux/dev_printk.h>
 923que debe usar para asegurarse de que los mensajes coincidan con el
 924dispositivo correcto y driver, y están etiquetados con el nivel correcto:
 925dev_err(), dev_warn(), dev_info(), y así sucesivamente. Para mensajes que
 926no están asociados con un dispositivo particular, <linux/printk.h> define
 927pr_notice(), pr_info(), pr_warn(), pr_err(), etc.
 928
 929Crear buenos mensajes de depuración puede ser todo un desafío; y una vez
 930los tiene, pueden ser de gran ayuda para la resolución remota de problemas.
 931Sin embargo, la impresión de mensajes de depuración se maneja de manera
 932diferente a la impresión de otros mensajes que no son de depuración.
 933Mientras que las otras funciones pr_XXX() se imprimen incondicionalmente,
 934pr_debug() no lo hace; se compila fuera por defecto, a menos que DEBUG sea
 935definido o se establezca CONFIG_DYNAMIC_DEBUG. Eso es cierto para dev_dbg()
 936también, y una convención relacionada usa VERBOSE_DEBUG para agregar
 937mensajes dev_vdbg() a los ya habilitados por DEBUG.
 938
 939Muchos subsistemas tienen opciones de depuración de Kconfig para activar
 940-DDEBUG en el Makefile correspondiente; en otros casos, los archivos
 941usan #define DEBUG. Y cuando un mensaje de depuración debe imprimirse
 942incondicionalmente, por ejemplo si es ya dentro de una sección #ifdef
 943relacionada con la depuración, printk(KERN_DEBUG ...) puede ser usado.
 944
 94514) Reservando memoria
 946----------------------
 947
 948El kernel proporciona los siguientes asignadores de memoria de propósito
 949general: kmalloc(), kzalloc(), kmalloc_array(), kcalloc(), vmalloc() y
 950vzalloc(). Consulte la documentación de la API para obtener más información.
 951a cerca de ellos. :ref:`Documentation/core-api/memory-allocation.rst
 952<memory_allocation>`
 953
 954La forma preferida para pasar el tamaño de una estructura es la siguiente:
 955
 956.. code-block:: c
 957
 958	p = kmalloc(sizeof(*p), ...);
 959
 960La forma alternativa donde se deletrea el nombre de la estructura perjudica
 961la legibilidad, y presenta una oportunidad para un error cuando se cambia
 962el tipo de variable de puntero, pero el tamaño correspondiente de eso que
 963se pasa a un asignador de memoria no.
 964
 965Convertir el valor devuelto, que es un puntero vacío, es redundante. La
 966conversión desde el puntero vacío a cualquier otro tipo de puntero está
 967garantizado por la programación en idioma C.
 968
 969La forma preferida para asignar una matriz es la siguiente:
 970
 971.. code-block:: c
 972
 973	p = kmalloc_array(n, sizeof(...), ...);
 974
 975La forma preferida para asignar una matriz a cero es la siguiente:
 976
 977.. code-block:: c
 978
 979	p = kcalloc(n, sizeof(...), ...);
 980
 981Ambos casos verifican el desbordamiento en el tamaño de asignación n *
 982sizeof (...), y devuelven NULL si esto ocurrió.
 983
 984Todas estas funciones de asignación genéricas emiten un volcado de pila
 985(" stack dump") en caso de fallo cuando se usan sin __GFP_NOWARN, por lo
 986que no sirve de nada emitir un mensaje de fallo adicional cuando se
 987devuelva NULL.
 988
 98915) La enfermedad de inline
 990----------------------------
 991
 992Parece haber una común percepción errónea de que gcc tiene una magica
 993opción "hazme más rápido" de aceleración, llamada ``inline`` (en línea).
 994Mientras que el uso de inlines puede ser apropiado (por ejemplo, como un
 995medio para reemplazar macros, consulte el Capítulo 12), muy a menudo no lo
 996es. El uso abundante de la palabra clave inline conduce a una mayor kernel,
 997que a su vez ralentiza el sistema en su conjunto, debido a una mayor huella
 998de icache para la CPU, y sencillamente porque hay menos memoria disponible
 999para el pagecache. Solo piense en esto; un fallo en la memoria caché de la
1000página provoca una búsqueda de disco, que tarda fácilmente 5 milisegundos.
1001Hay MUCHOS ciclos de CPU que puede entrar en estos 5 milisegundos.
1002
1003Una razonable regla general es no poner funciones inline que tengan más de
10043 líneas de código en ellas. Una excepción a esta regla son los casos en
1005que se sabe que un parámetro es una constante en tiempo de compilación, y
1006como resultado de esto, usted *sabe*, el compilador podrá optimizar la
1007mayor parte de su función en tiempo de compilación. Para un buen ejemplo de
1008este último caso, véase la función en línea kmalloc().
1009
1010A menudo, la gente argumenta que agregar funciones en línea que son
1011estáticas y se usan solo una vez, es siempre una victoria ya que no hay
1012perdida de espacio. Mientras esto es técnicamente correcto, gcc es capaz de
1013incorporarlos automáticamente sin ayuda, y esta el problema de
1014mantenimiento de eliminar el inline, cuando un segundo usuario supera el
1015valor potencial de la pista que le dice a gcc que haga algo que habría
1016hecho de todos modos.
1017
101816) Valores devueltos por función y sus nombres
1019-----------------------------------------------
1020
1021Las funciones pueden devolver valores de muchos tipos diferentes, y uno de
1022lo más común es un valor que indica si la función tuvo éxito o ha fallado.
1023Dicho valor se puede representar como un número entero de código de error
1024(-Exxx = falla, 0 = éxito) o un booleano ``con éxito`` (0 = falla, distinto
1025de cero = éxito).
1026
1027La mezcla de estos dos tipos de representaciones es una fuente fértil de
1028errores difíciles de encontrar. Si el lenguaje C incluyera una fuerte
1029distinción entre enteros y booleanos, el compilador encontraría estos
1030errores por nosotros... pero no lo hace. Para ayudar a prevenir tales
1031errores, siga siempre esta convención::
1032
1033	Si el nombre de una función es una acción o un comando imperativo,
1034	la función debe devolver un número entero de código de error. si el nombre
1035	es un predicado, la función debe devolver un valor booleano "exitoso".
1036
1037Por ejemplo, ``agregar trabajo`` es un comando, y la función
1038agregar_trabajo() devuelve 0 en caso de éxito o -EBUSY en caso de fracaso.
1039De la misma manera, ``dispositivo PCI presente`` es un predicado, y la
1040función pci_dev_present() devuelve 1 si tiene éxito en encontrar un
1041dispositivo coincidente o 0 si no es así.
1042
1043Todas las funciones EXPORTed (exportadas) deben respetar esta convención,
1044al igual que todas las funciones publicas. Las funciones privadas
1045(estáticas) no lo necesitan, pero es recomendado que lo hagan.
1046
1047Las funciones cuyo valor devuelto es el resultado real de un cálculo, en
1048lugar de una indicación de si el cómputo tuvo éxito, no están sujetas a
1049esta regla. Generalmente indican fallo al devolver valores fuera del rango
1050de resultados. Los ejemplos típicos serían funciones que devuelven
1051punteros; estos usan NULL o el mecanismo ERR_PTR para informar de fallos.
1052
105317) Usando bool
1054----------------
1055
1056El tipo bool del kernel Linux es un alias para el tipo C99 _Bool. Los
1057valores booleanos pueden solo evaluar a 0 o 1, y la conversión implícita o
1058explícita a bool convierte automáticamente el valor en verdadero o falso.
1059Cuando se utilizan tipos booleanos,
1060!! no se necesita construcción, lo que elimina una clase de errores.
1061
1062Cuando se trabaja con valores booleanos, se deben usar las definiciones
1063verdadera y falsa, en lugar de 1 y 0.
1064
1065Los tipos de devolución de función bool y las variables de pila siempre
1066se pueden usar cuando esto sea adecuado. Se recomienda el uso de bool para
1067mejorar la legibilidad y, a menudo, es una mejor opción que 'int' para
1068almacenar valores booleanos.
1069
1070No use bool si el diseño de la línea de caché o el tamaño del valor son
1071importantes, ya que su tamaño y la alineación varía según la arquitectura
1072compilada. Las estructuras que son optimizadas para la alineación y el
1073tamaño no debe usar bool.
1074
1075Si una estructura tiene muchos valores verdadero/falso, considere
1076consolidarlos en un bitfield con miembros de 1 bit, o usando un tipo de
1077ancho fijo apropiado, como u8.
1078
1079De manera similar, para los argumentos de función, se pueden consolidar
1080muchos valores verdaderos/falsos en un solo argumento bit a bit 'flags' y
1081'flags' a menudo, puede ser una alternativa de argumento más legible si los
1082sitios de llamada tienen constantes desnudas de tipo verdaderas/falsas.
1083
1084De lo contrario, el uso limitado de bool en estructuras y argumentos puede
1085mejorar la legibilidad.
1086
108718) No reinvente las macros del kernel
1088---------------------------------------
1089
1090El archivo de cabecera include/linux/kernel.h contiene una serie de macros
1091que debe usar, en lugar de programar explícitamente alguna variante de
1092estos por usted mismo. Por ejemplo, si necesita calcular la longitud de una
1093matriz, aproveche la macro
1094
1095.. code-block:: c
1096
1097	#define ARRAY_SIZE(x) (sizeof(x) / sizeof((x)[0]))
1098
1099De manera similar, si necesita calcular el tamaño de algún miembro de la
1100estructura, use
1101
1102.. code-block:: c
1103
1104	#define sizeof_field(t, f) (sizeof(((t*)0)->f))
1105
1106También hay macros min() y max() que realizan una verificación estricta de
1107tipos si lo necesita. Siéntase libre de leer detenidamente ese archivo de
1108encabezado para ver qué más ya está definido y que no debe reproducir en su
1109código.
1110
111119) Editores modeline y otros desastres
1112---------------------------------------
1113
1114Algunos editores pueden interpretar la información de configuración
1115incrustada en los archivos fuente, indicado con marcadores especiales. Por
1116ejemplo, emacs interpreta las líneas marcadas como esto:
1117
1118.. code-block:: c
1119
1120	-*- mode: c -*-
1121
1122O así:
1123
1124.. code-block:: c
1125
1126	/*
1127	Local Variables:
1128	compile-command: "gcc -DMAGIC_DEBUG_FLAG foo.c"
1129	End:
1130	*/
1131
1132Vim interpreta los marcadores que se ven así:
1133
1134.. code-block:: c
1135
1136	/* vim:set sw=8 noet */
1137
1138No incluya ninguno de estos en los archivos fuente. La gente tiene sus
1139propias configuraciones del editor, y sus archivos de origen no deben
1140anularlos. Esto incluye marcadores para sangría y configuración de modo.
1141La gente puede usar su propio modo personalizado, o puede tener algún otro
1142método mágico para que la sangría funcione correctamente.
1143
1144
114520) Ensamblador inline
1146-----------------------
1147
1148En el código específico de arquitectura, es posible que deba usar
1149ensamblador en línea para interactuar con funcionalidades de CPU o
1150plataforma. No dude en hacerlo cuando sea necesario. Sin embargo, no use
1151ensamblador en línea de forma gratuita cuando C puede hacer el trabajo.
1152Puede y debe empujar el hardware desde C cuando sea posible.
1153
1154Considere escribir funciones auxiliares simples que envuelvan bits comunes
1155de ensamblador, en lugar de escribirlos repetidamente con ligeras
1156variaciones. Recuerde que el ensamblador en línea puede usar parámetros C.
1157
1158Las funciones de ensamblador grandes y no triviales deben ir en archivos .S,
1159con su correspondientes prototipos de C definidos en archivos de encabezado
1160en C. Los prototipos de C para el ensamblador deben usar ``asmlinkage``.
1161
1162Es posible que deba marcar su declaración asm como volátil, para evitar que
1163GCC la elimine si GCC no nota ningún efecto secundario. No siempre es
1164necesario hacerlo, sin embargo, y hacerlo innecesariamente puede limitar la
1165optimización.
1166
1167Al escribir una sola declaración de ensamblador en línea que contiene
1168múltiples instrucciones, ponga cada instrucción en una línea separada en
1169una string separada, y termine cada string excepto la última con ``\n\t``
1170para indentar correctamente la siguiente instrucción en la salida en
1171ensamblador:
1172
1173.. code-block:: c
1174
1175	asm ("magic %reg1, #42\n\t"
1176	     "more_magic %reg2, %reg3"
1177	     : /* outputs */ : /* inputs */ : /* clobbers */);
1178
117921) Compilación condicional
1180---------------------------
1181
1182Siempre que sea posible, no use condicionales de preprocesador (#if,
1183#ifdef) en archivos .c; de lo contrario, el código es más difícil de leer y
1184la lógica más difícil de seguir. En cambio, use dichos condicionales en un
1185archivo de encabezado que defina funciones para usar en esos archivos .c,
1186proporcionando versiones de código auxiliar sin operación en el caso #else,
1187y luego llame a estas funciones incondicionalmente desde archivos .c. El
1188compilador evitará generar cualquier código para las llamadas restantes,
1189produciendo resultados idénticos, pero la lógica es fácil de seguir.
1190
1191Prefiera compilar funciones completas, en lugar de porciones de funciones o
1192porciones de expresiones. En lugar de poner un ifdef en una expresión,
1193divida la totalidad de la expresión con una función de ayuda independiente
1194y aplique el condicional a esa función.
1195
1196Si tiene una función o variable que puede potencialmente quedar sin usar en
1197una configuración en particular, y el compilador advertiría sobre su
1198definición sin usar, marque la definición como __maybe_unused en lugar de
1199envolverla en un preprocesador condicional. (Sin embargo, si una función o
1200variable *siempre* acaba sin ser usada, bórrela.)
1201
1202Dentro del código, cuando sea posible, use la macro IS_ENABLED para
1203convertir un símbolo Kconfig en una expresión booleana de C, y utilícelo en
1204un condicional de C normal:
1205
1206.. code-block:: c
1207
1208	if (IS_ENABLED(CONFIG_SOMETHING)) {
1209		...
1210	}
1211
1212El compilador "doblará"" constantemente el condicional e incluirá o
1213excluirá el bloque de código al igual que con un #ifdef, por lo que esto no
1214agregará ningún tiempo de gastos generales en ejecución. Sin embargo, este
1215enfoque todavía permite que el compilador de C vea el código dentro del
1216bloque, y verifique que sea correcto (sintaxis, tipos, símbolo, referencias,
1217etc.). Por lo tanto, aún debe usar un #ifdef si el código dentro del bloque
1218hace referencia a símbolos que no existirán si no se cumple la condición.
1219
1220Al final de cualquier bloque #if o #ifdef no trivial (más de unas pocas
1221líneas), incluya un comentario después de #endif en la misma línea,
1222anotando la expresión condicional utilizada. Por ejemplo:
1223
1224.. code-block:: c
1225
1226	#ifdef CONFIG_SOMETHING
1227	...
1228	#endif /* CONFIG_SOMETHING */
1229
123022) No rompa el kernel
1231-----------------------
1232
1233En general, la decisión de romper el kernel pertenece al usuario, más que
1234al desarrollador del kernel.
1235
1236Evite el panic()
1237****************
1238
1239panic() debe usarse con cuidado y principalmente solo durante el arranque
1240del sistema. panic() es, por ejemplo, aceptable cuando se queda sin memoria
1241durante el arranque y no puede continuar.
1242
1243Use WARN() en lugar de BUG()
1244****************************
1245
1246No agregue código nuevo que use cualquiera de las variantes BUG(), como
1247BUG(), BUG_ON() o VM_BUG_ON(). En su lugar, use una variante WARN*(),
1248preferiblemente WARN_ON_ONCE(), y posiblemente con código de recuperación.
1249El código de recuperación no es requerido si no hay una forma razonable de
1250recuperar, al menos parcialmente.
1251
1252"Soy demasiado perezoso para tener en cuenta los errores" no es una excusa
1253para usar BUG(). Importantes corrupciones internas sin forma de continuar
1254aún pueden usar BUG(), pero necesitan una buena justificación.
1255
1256Use WARN_ON_ONCE() en lugar de WARN() o WARN_ON()
1257*************************************************
1258
1259Generalmente, se prefiere WARN_ON_ONCE() a WARN() o WARN_ON(), porque es
1260común que una condición de advertencia dada, si ocurre, ocurra varias
1261veces. Esto puede llenar el registro del kernel, e incluso puede ralentizar
1262el sistema lo suficiente como para que el registro excesivo se convierta en
1263su propio, adicional problema.
1264
1265No haga WARN a la ligera
1266************************
1267
1268WARN*() está diseñado para situaciones inesperadas que nunca deberían
1269suceder. Las macros WARN*() no deben usarse para nada que se espera que
1270suceda durante un funcionamiento normal. No hay "checkeos" previos o
1271posteriores a la condición, por ejemplo. De nuevo: WARN*() no debe usarse
1272para una condición esperada que vaya a activarse fácilmente, por ejemplo,
1273mediante acciones en el espacio del usuario. pr_warn_once() es una
1274alternativa posible, si necesita notificar al usuario de un problema.
1275
1276No se preocupe sobre panic_on_warn de usuarios
1277**********************************************
1278
1279Algunas palabras más sobre panic_on_warn: Recuerde que ``panic_on_warn`` es
1280una opción disponible del kernel, y que muchos usuarios configuran esta
1281opción. Esta es la razón por la que hay un artículo de "No haga WARN a la
1282ligera", arriba. Sin embargo, la existencia de panic_on_warn de usuarios no
1283es una razón válida para evitar el uso juicioso de WARN*(). Esto se debe a
1284que quien habilita panic_on_warn, explícitamente pidió al kernel que
1285fallara si se dispara un WARN*(), y tales usuarios deben estar preparados
1286para afrontar las consecuencias de un sistema que es algo más probable que
1287se rompa.
1288
1289Use BUILD_BUG_ON() para aserciones en tiempo de compilación
1290***********************************************************
1291
1292El uso de BUILD_BUG_ON() es aceptable y recomendado, porque es una aserción
1293en tiempo de compilación, que no tiene efecto en tiempo de ejecución.
1294
1295Apéndice I) Referencias
1296-----------------------
1297
1298The C Programming Language, Segunda edicion
1299por Brian W. Kernighan and Dennis M. Ritchie.
1300Prentice Hall, Inc., 1988.
1301ISBN 0-13-110362-8 (paperback), 0-13-110370-9 (hardback).
1302
1303The Practice of Programming
1304por Brian W. Kernighan and Rob Pike.
1305Addison-Wesley, Inc., 1999.
1306ISBN 0-201-61586-X.
1307
1308manuales GCC - en cumplimiento con K&R y este texto - para cpp, gcc,
1309detalles de gcc y sangría, todo disponible en https://www.gnu.org/manual/
1310
1311WG14 es el grupo de trabajo de estandarización internacional de la
1312programación en lenguaje C, URL: http://www.open-std.org/JTC1/SC22/WG14/
1313
1314:ref:`process/coding-style.rst <codingstyle>` del kernel, por greg@kroah.com at OLS 2002:
1315http://www.kroah.com/linux/talks/ols_2002_kernel_codingstyle_talk/html/