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
8 Estilo en el código del kernel Linux
9 =====================================
10
11 Este es un breve documento que describe el estilo preferido en el código
12 del kernel Linux. El estilo de código es muy personal y no **forzaré** mi
13 puntos de vista sobre nadie, pero esto vale para todo lo que tengo que
14 mantener, y preferiría que para la mayoría de otras cosas también. Por
15 favor, por lo menos considere los argumentos expuestos aquí.
16
17 En primer lugar, sugeriría imprimir una copia de los estándares de código
18 GNU, y NO leerlo. Quémelos, es un gran gesto simbólico.
19
20 De todos modos, aquí va:
21
22
23 1) Sangría
24 -----------
25
26 Las tabulaciones tienen 8 caracteres y, por lo tanto, las sangrías también
27 tienen 8 caracteres. Hay movimientos heréticos que intentan hacer sangría
28 de 4 (¡o incluso 2!) caracteres de longitud, y eso es similar a tratar de
29 definir el valor de PI como 3.
30
31 Justificación: La idea detrás de la sangría es definir claramente dónde
32 comienza y termina un bloque de control. Especialmente, cuando ha estado
33 buscando en su pantalla durante 20 horas seguidas, le resultará mucho más
34 fácil ver cómo funciona la sangría si tiene sangrías grandes.
35
36 Bueno, algunas personas dirán que tener sangrías de 8 caracteres hace que
37 el código se mueva demasiado a la derecha y dificulta la lectura en una
38 pantalla de terminal de 80 caracteres. La respuesta a eso es que si
39 necesita más de 3 niveles de sangría, está en apuros de todos modos y
40 debería arreglar su programa.
41
42 En resumen, las sangrías de 8 caracteres facilitan la lectura y tienen la
43 ventaja añadida de advertirle cuando está anidando sus funciones demasiado
44 profundo. Preste atención a esa advertencia.
45
46 La forma preferida de facilitar múltiples niveles de sangría en una
47 declaración de switch es para alinear el ``switch`` y sus etiquetas
48 ``case`` subordinadas en la misma columna, en lugar de hacer ``doble
49 sangrí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
70 No ponga varias declaraciones en una sola línea a menos que tenga algo que
71 ocultar:
72
73 .. code-block:: c
74
75 if (condición) haz_esto;
76 haz_otra_cosa;
77
78 No use comas para evitar el uso de llaves:
79
80 .. code-block:: c
81
82 if (condición)
83 haz_esto(), haz_eso();
84
85 Siempre use llaves para múltiples declaraciones:
86
87 .. code-block:: c
88
89 if (condición) {
90 haz_esto();
91 haz_eso();
92 }
93
94 Tampoco ponga varias asignaciones en una sola línea. El estilo de código
95 del kernel es súper simple. Evite las expresiones engañosas.
96
97
98 Aparte de los comentarios, la documentación y excepto en Kconfig, los
99 espacios nunca se utilizan para la sangría, y el ejemplo anterior se rompe
100 deliberadamente.
101
102 Consiga un editor decente y no deje espacios en blanco al final de las
103 líneas.
104
105 2) Rompiendo líneas y strings largos
106 ------------------------------------
107
108 El estilo de código tiene todo que ver con la legibilidad y la
109 mantenibilidad usando herramientas disponibles comúnmente.
110
111 El límite preferido en la longitud de una sola línea es de 80 columnas.
112
113 Las declaraciones de más de 80 columnas deben dividirse en partes, a menos
114 que exceder las 80 columnas aumente significativamente la legibilidad y no
115 oculte información.
116
117 Los descendientes siempre son sustancialmente más cortos que el padre y
118 se colocan sustancialmente a la derecha. Un estilo muy usado es alinear
119 descendientes a un paréntesis de función abierto.
120
121 Estas mismas reglas se aplican a los encabezados de funciones con una larga
122 lista de argumentos.
123
124 Sin embargo, nunca rompa los strings visibles para el usuario, como los
125 mensajes printk, porque eso rompe la capacidad de grep a estos.
126
127
128 3) Colocación de llaves y espacios
129 ----------------------------------
130
131 El otro problema que siempre surge en el estilo C es la colocación de
132 llaves. A diferencia del tamaño de la sangría, existen pocas razones
133 técnicas para elegir una estrategia de ubicación sobre la otra, pero la
134 forma preferida, como mostraron los profetas Kernighan y Ritchie, es poner
135 la llave de apertura en la línea, y colocar la llave de cierre primero,
136 así:
137
138 .. code-block:: c
139
140 if (x es verdad) {
141 hacemos y
142 }
143
144 Esto 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
160 Sin embargo, hay un caso especial, a saber, las funciones: tienen la llave
161 de 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
170 Gente hereje de todo el mundo ha afirmado que esta inconsistencia es...
171 bueno... 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
173 especiales de todos modos (no puede anidarlas en C).
174
175 Tenga 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
177 declaración, es decir, un ``while`` en una sentencia do o un ``else`` en
178 una sentencia if, como en:
179
180 .. code-block:: c
181
182 do {
183 cuerpo del bucle do
184 } while (condition);
185
186 y
187
188 .. code-block:: c
189
190 if (x == y) {
191 ..
192 } else if (x > y) {
193 ...
194 } else {
195 ....
196 }
197
198 Justificación: K&R.
199
200 Además, tenga en cuenta que esta colocación de llaves también minimiza el
201 número de líneas vacías (o casi vacías), sin pérdida de legibilidad. Así,
202 como el suministro de nuevas líneas en su pantalla no es un recurso
203 renovable (piense en pantallas de terminal de 25 líneas), tienes más líneas
204 vacías para poner comentarios.
205
206 No use llaves innecesariamente donde una sola declaración sea suficiente.
207
208 .. code-block:: c
209
210 if (condition)
211 accion();
212
213 y
214
215 .. code-block:: none
216
217 if (condición)
218 haz_esto();
219 else
220 haz_eso();
221
222 Esto no aplica si solo una rama de una declaración condicional es una sola
223 declaració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
234 Ademá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
243 3.1) Espacios
244 *************
245
246 El estilo del kernel Linux para el uso de espacios depende (principalmente)
247 del uso de función versus uso de palabra clave. Utilice un espacio después
248 de (la mayoría de) las palabras clave. Las excepciones notables son sizeof,
249 typeof, alignof y __attribute__, que parecen algo así como funciones (y
250 generalmente se usan con paréntesis en Linux, aunque no son requeridos en
251 el idioma, como en: ``sizeof info`` después de que ``struct fileinfo info;``
252 se declare).
253
254 Así que use un espacio después de estas palabras clave::
255
256 if, switch, case, for, do, while
257
258 pero no con sizeof, typeof, alignof, o __attribute__. Por ejemplo,
259
260 .. code-block:: c
261
262
263 s = sizeof(struct file);
264
265 No agregue espacios alrededor (dentro) de expresiones entre paréntesis.
266 Este ejemplo es **malo**:
267
268 .. code-block:: c
269
270
271 s = sizeof( struct file );
272
273 Al declarar datos de puntero o una función que devuelve un tipo de puntero,
274 el uso preferido de ``*`` es adyacente al nombre del dato o nombre de la
275 funció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
284 Use un espacio alrededor (a cada lado de) la mayoría de los operadores
285 binarios y ternarios, como cualquiera de estos::
286
287 = + - < > * / % | & ^ <= >= == != ? :
288
289 pero sin espacio después de los operadores unarios::
290
291 & * + - ~ ! sizeof typeof alignof __attribute__ defined
292
293 sin espacio antes de los operadores unarios de incremento y decremento del
294 sufijo::
295
296 ++ --
297
298 y sin espacio alrededor de los operadores de miembros de estructura ``.`` y
299 ``->``.
300
301 No 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
303 nuevas líneas como sea apropiado, para que pueda comenzar a escribir la
304 siguiente línea de código de inmediato. Sin embargo, algunos de estos
305 editores no eliminan los espacios en blanco si finalmente no termina
306 poniendo una línea de código allí, como si dejara una línea en blanco. Como
307 resultado, termina con líneas que contienen espacios en blanco al final.
308
309 Git le advertirá sobre los parches que introducen espacios en blanco al
310 final y puede, opcionalmente, eliminar los espacios en blanco finales por
311 usted; sin embargo, si se aplica una serie de parches, esto puede hacer que
312 los parches posteriores de la serie fallen al cambiar sus líneas de
313 contexto.
314
315
316 4) Nomenclatura
317 ---------------
318
319 C es un lenguaje espartano, y sus convenciones de nomenclatura deberían
320 seguir su ejemplo. A diferencia de los programadores de Modula-2 y Pascal,
321 los programadores de C no usan nombres cuquis como
322 EstaVariableEsUnContadorTemporal. Un programador de C lo llamaría
323 variable ``tmp``, que es mucho más fácil de escribir, y no es mas difícil
324 de comprender.
325
326 SIN EMBARGO, mientras que los nombres de mayúsculas y minúsculas están mal
327 vistos, los nombres descriptivos para las variables globales son
328 imprescindibles. Llamar a una función global ``foo`` es un delito.
329
330 Una variable GLOBAL (para usar solo si **realmente** las necesita) necesita
331 tener un nombre descriptivo, al igual que las funciones globales. Si tiene
332 una 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
335 Codificar el tipo de una función en el nombre (lo llamado notación húngara)
336 es estúpido: el compilador conoce los tipos de todos modos y puede
337 verificar estos, y solo confunde al programador.
338
339 Los nombres de las variables LOCALES deben ser breves y directos. Si usted
340 tiene algún contador aleatorio de tipo entero, probablemente debería
341 llamarse ``i``. Llamarlo ``loop_counter`` no es productivo, si no hay
342 posibilidad de ser mal entendido. De manera similar, ``tmp`` puede ser casi
343 cualquier tipo de variable que se utiliza para contener un valor temporal.
344
345 Si tiene miedo de mezclar los nombres de las variables locales, tiene otro
346 problema, que se denomina síndrome de
347 función-crecimiento-desequilibrio-de-hormona. Vea el capítulo 6 (Funciones).
348
349 Para 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
353 Los 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
360 Los reemplazos recomendados para 'backlist / whitelist' son:
361 'denylist / allowlist'
362 'blocklist / passlist'
363
364 Las excepciones para la introducción de nuevos usos son mantener en espacio
365 de usuario una ABI/API, o al actualizar la especificación del código de un
366 hardware o protocolo existente (a partir de 2020) que requiere esos
367 términos. Para nuevas especificaciones, traduzca el uso de la terminología
368 de la especificación al estándar de código del kernel donde sea posible.
369
370 5) Typedefs
371 -----------
372
373 Por favor no use cosas como ``vps_t``.
374 Es un **error** usar typedef para estructuras y punteros. cuando ve un
375
376 .. code-block:: c
377
378
379 vps_t a;
380
381 en el código fuente, ¿qué significa?
382 En cambio, si dice
383
384 .. code-block:: c
385
386 struct virtual_container *a;
387
388 puede decir qué es ``a`` en realidad.
389
390 Mucha 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
448 Tal vez también haya otros casos, pero la regla básicamente debería ser
449 NUNCA JAMÁS use un typedef a menos que pueda coincidir claramente con una
450 de estas reglas.
451
452 En general, un puntero o una estructura que tiene elementos que pueden
453 ser razonablemente accedidos directamente, **nunca** deben ser un typedef.
454
455 6) Funciones
456 ------------
457
458 Las funciones deben ser cortas y dulces, y hacer una sola cosa. Deberían
459 caber en una o dos pantallas de texto (el tamaño de pantalla ISO/ANSI es
460 80x24, como todos sabemos), y hacer una cosa y hacerla bien.
461
462 La longitud máxima de una función es inversamente proporcional a la
463 complejidad y el nivel de sangría de esa función. Entonces, si tiene una
464 función conceptualmente simple que es solo una larga (pero simple)
465 declaración de case, donde tiene que hacer un montón de pequeñas cosas para
466 un montón de diferentes casos, está bien tener una función más larga.
467
468 Sin embargo, si tiene una función compleja y sospecha que un estudiante de
469 primer año de secundaria menos que dotado podría no comprender de qué se
470 trata la función, debe adherirse a los límites máximos tanto más de
471 cerca. Use funciones auxiliares con nombres descriptivos (puede pedirle al
472 compilador que los alinee si cree que es crítico para el rendimiento, y
473 probablemente lo hará mejor de lo que usted hubiera hecho).
474
475 Otra medida de la función es el número de variables locales. Estas no deben
476 exceder de 5 a 10, o está haciendo algo mal. Piense de nuevo en la función
477 y divida en partes más pequeñas. Un cerebro humano puede generalmente
478 realiza un seguimiento de aproximadamente 7 cosas diferentes, cualquier
479 elemento más y se confunde. Usted sabe que es brillante, pero tal vez le
480 gustaría entender lo que hizo dentro de 2 semanas.
481
482 En los archivos fuente, separe las funciones con una línea en blanco. Si la
483 función es exportada, la macro **EXPORT** debería ponerse inmediatamente
484 despué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
494 6.1) Prototipos de funciones
495 ****************************
496
497 En los prototipos de funciones, incluya nombres de parámetros con sus tipos
498 de datos. Aunque esto no es requerido por el lenguaje C, se prefiere en
499 Linux porque es una forma sencilla de añadir información valiosa para el
500 lector.
501
502 No utilice la palabra clave ``extern`` con declaraciones de función ya que
503 esto hace las líneas más largas y no es estrictamente necesario.
504
505 Al escribir prototipos de funciones, mantenga el `orden de los elementos regular
506 <https://lore.kernel.org/mm-commits/CAHk-=wiOCLRny5aifWNhr621kYrJwhfURsa0vFPeUEm8mF0ufg@mail.gmail.com/">https://lore.kernel.org/mm-commits/CAHk-=wiOCLRny5aifWNhr621kYrJwhfURsa0vFPeUEm8mF0ufg@mail.gmail.com/>`_.
507 Por 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
512 El 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
528 Tenga en cuenta que para una **definición** de función (es decir, el cuerpo
529 real de la función), el compilador no permite atributos de parámetros de
530 función después de parámetros de la función. En estos casos, deberán ir
531 tras los atributos de clase (por ejemplo, tenga en cuenta el cambio de
532 posición de ``__printf(4, 5)`` a continuación, en comparación con el
533 ejemplo 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
541 7) Salida centralizada de funciones
542 -----------------------------------
543
544 Aunque desaprobado por algunas personas, el equivalente de la instrucción
545 goto es utilizado con frecuencia por los compiladores, en forma de
546 instrucción de salto incondicional.
547
548 La declaración goto es útil cuando una función sale desde múltiples
549 ubicaciones y se deben realizar algunos trabajos comunes, como la limpieza.
550 Si no se necesita limpieza, entonces simplemente haga return directamente.
551
552 Elija nombres de etiquetas que digan qué hace el goto o por qué existe el
553 goto. Un ejemplo de un buen nombre podría ser ``out_free_buffer:``
554 (``salida_liberar_buffer``) si al irse libera ``buffer``. Evite usar
555 nombres GW-BASIC como ``err1:`` y ``err2:``, ya que tendría que volver a
556 numerarlos si alguna vez agrega o elimina rutas de salida, y hacen que sea
557 difícil de verificar que sean correctos, de todos modos.
558
559 La 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
591 Un tipo común de error a tener en cuenta es "un error de error" que es algo
592 así:
593
594 .. code-block:: c
595
596 err:
597 kfree(foo->bar);
598 kfree(foo);
599 return ret;
600
601 El error en este código es que en algunas rutas de salida, ``foo`` es NULL.
602 Normalmente 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
613 Idealmente, debería simular errores para probar todas las rutas de salida.
614
615
616 8) Comentarios
617 --------------
618
619 Los comentarios son buenos, pero también existe el peligro de comentar
620 demasiado. NUNCA trate de explicar CÓMO funciona su código en un
621 comentario: 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
623 escrito.
624
625 Generalmente, desea que sus comentarios digan QUÉ hace su código, no CÓMO.
626 Además, trate de evitar poner comentarios dentro del cuerpo de una función:
627 si la función es tan compleja que necesita comentar por separado partes de
628 esta, probablemente debería volver al capítulo 6 una temporada. Puede
629 hacer pequeños comentarios para notar o advertir sobre algo particularmente
630 inteligente (o feo), pero trate de evitar el exceso. En su lugar, ponga los
631 comentarios al principio de la función, diga a la gente lo que hace y
632 posiblemente POR QUÉ hace esto.
633
634 Al comentar las funciones de la API del kernel, utilice el formato
635 kernel-doc. Consulte los archivos en :ref:`Documentation/doc-guide/ <doc_guide>`
636 y ``scripts/kernel-doc`` para más detalles.
637
638 El 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
651 Para archivos en net/ y drivers/net/, el estilo preferido para comentarios
652 largos (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
663 También es importante comentar los datos, ya sean tipos básicos o
664 derivados. Para este fin, use solo una declaración de datos por línea (sin
665 comas para múltiples declaraciones de datos). Esto le deja espacio para un
666 pequeño comentario sobre cada elemento, explicando su uso.
667
668 9) Has hecho un desastre
669 ---------------------------
670
671 Está bien, todos lo hacemos. Probablemente un antiguo usuario de Unix le
672 haya dicho que ``GNU emacs`` formatea automáticamente las fuentes C por
673 usted, y ha notado que sí, lo hace, pero los por defecto que tiene son
674 menos que deseables (de hecho, son peores que los aleatorios) escribiendo -
675 un número infinito de monos escribiendo en GNU emacs nunca harán un buen
676 programa).
677
678 Por lo tanto, puede deshacerse de GNU emacs o cambiarlo y usar valores más
679 sanos. 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
731 Esto hará que emacs funcione mejor con el estilo de código del kernel para
732 C en archivos bajo ``~/src/linux-trees``.
733
734 Pero incluso si no logra que emacs realice un formateo correcto, no todo
735 está perdido: use ``indent``.
736
737 Ahora bien, de nuevo, la sangría de GNU tiene la misma configuración de
738 muerte cerebral que GNU emacs tiene, por lo que necesita darle algunas
739 opciones de línea de comando. Sin embargo, eso no es tan malo, porque
740 incluso los creadores de GNU indent reconocen la autoridad de K&R (la gente
741 de GNU no es mala, solo están gravemente equivocados en este asunto), por
742 lo 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
744 con ese estilo.
745
746 ``indent`` tiene muchas opciones, y especialmente cuando se trata de
747 comentar reformateos, es posible que desee echar un vistazo a la página del
748 manual. Pero recuerde: ``indent`` no es la solución para una mala
749 programación.
750
751 Tenga en cuenta que también puede usar la herramienta ``clang-format`` para
752 ayudarlo con estas reglas, para volver a formatear rápidamente partes de su
753 código automáticamente, y revisar archivos completos para detectar errores
754 de estilo del código, errores tipográficos y posibles mejoras. También es
755 útil para ordenar ``#includes``, para alinear variables/macros, para
756 redistribuir texto y otras tareas similares. Vea el archivo
757 :ref:`Documentation/dev-tools/clang-format.rst <clangformat>` para más
758 detalles.
759
760 10) Archivos de configuración de Kconfig
761 ----------------------------------------
762
763 Para todos los archivos de configuración de Kconfig* en todo el árbol
764 fuente, 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
766 ayuda 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
777 Características seriamente peligrosas (como soporte de escritura para
778 ciertos filesystems) deben anunciar esto de forma destacada en su cadena de
779 solicitud::
780
781 config ADFS_FS_RW
782 bool "ADFS write support (DANGEROUS)"
783 depends on ADFS_FS
784 ...
785
786 Para obtener la documentación completa sobre los archivos de configuración,
787 consulte el archivo Documentation/kbuild/kconfig-language.rst.
788
789
790 11) Estructuras de datos
791 ------------------------
792
793 Las estructuras de datos que tienen visibilidad fuera del contexto de un
794 solo subproceso en el que son creadas y destruidas, siempre debe tener
795 contadores 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
797 que significa que absolutamente **tiene** para hacer referencia y contar
798 todos sus usos.
799
800 El conteo de referencias significa que puede evitar el bloqueo y permite
801 que múltiples usuarios tengan acceso a la estructura de datos en paralelo -
802 y no tengan que preocuparse de que la estructura, de repente, desaparezca
803 debajo de su control, solo porque durmieron o hicieron otra cosa por un
804 tiempo.
805
806 Tenga en cuenta que el bloqueo **no** reemplaza el recuento de referencia.
807 El bloqueo se utiliza para mantener la coherencia de las estructuras de
808 datos, mientras que la referencia y contar es una técnica de gestión de
809 memoria. Por lo general, ambos son necesarios, y no deben confundirse entre
810 sí.
811
812 De hecho, muchas estructuras de datos pueden tener dos niveles de conteo de
813 referencias, cuando hay usuarios de diferentes ``clases``. El conteo de
814 subclases cuenta el número de usuarios de la subclase y disminuye el conteo
815 global solo una vez, cuando el recuento de subclases llega a cero.
816
817 Se pueden encontrar ejemplos de este tipo de ``recuento de referencias de
818 niveles múltiples`` en la gestión de memoria (``struct mm_struct``:
819 mm_users y mm_count), y en código del sistema de archivos
820 (``struct super_block``: s_count y s_active).
821
822 Recuerde: si otro hilo puede encontrar su estructura de datos y usted no
823 tiene un recuento de referencias, es casi seguro que tiene un error.
824
825 12) Macros, Enums y RTL
826 ------------------------
827
828 Los 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
835 Se prefieren los enums cuando se definen varias constantes relacionadas.
836
837 Se aprecian los nombres de macro en MAYÚSCULAS, pero las macros que se
838 asemejan a funciones puede ser nombradas en minúscula.
839
840 Generalmente, las funciones en línea son preferibles a las macros que se
841 asemejan a funciones.
842
843 Las 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
853 Cosas a evitar al usar macros:
854
855 1) 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
865 es una **muy** mala idea. Parece una llamada de función pero sale de la
866 función de ``llamada``; no rompa los analizadores internos de aquellos que
867 leerán el código.
868
869 2) 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
875 puede parecer algo bueno, pero es confuso como el infierno cuando uno lee
876 el código, y es propenso a romperse por cambios aparentemente inocentes.
877
878 3) macros con argumentos que se usan como valores l: FOO(x) = y; le van
879 a morder si alguien, por ejemplo, convierte FOO en una función en línea.
880
881 4) olvidarse de la precedencia: las macros que definen constantes usando
882 expresiones deben encerrar la expresión entre paréntesis. Tenga cuidado con
883 problemas similares con macros usando parámetros.
884
885 .. code-block:: c
886
887 #define CONSTANTE 0x4000
888 #define CONSTEXP (CONSTANTE | 3)
889
890 5) colisiones de espacio de nombres ("namespace") al definir variables
891 locales 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
902 ret es un nombre común para una variable local -es menos probable que
903 __foo_ret colisione (coincida) con una variable existente.
904
905 El manual de cpp trata las macros de forma exhaustiva. El manual interno de
906 gcc también cubre RTL, que se usa frecuentemente con lenguaje ensamblador
907 en el kernel.
908
909 13) Imprimir mensajes del kernel
910 --------------------------------
911
912 A los desarrolladores del kernel les gusta ser vistos como alfabetizados.
913 Cuide la ortografía de los mensajes del kernel para causar una buena
914 impresión. No utilice contracciones incorrectas como ``dont``; use
915 ``do not`` o ``don't`` en su lugar. Haga sus mensajes concisos, claros e
916 inequívocos.
917
918 Los mensajes del kernel no tienen que terminar con un punto.
919
920 Imprimir números entre paréntesis (%d) no agrega valor y debe evitarse.
921
922 Hay varias modelos de macros de diagnóstico de driver en <linux/dev_printk.h>
923 que debe usar para asegurarse de que los mensajes coincidan con el
924 dispositivo correcto y driver, y están etiquetados con el nivel correcto:
925 dev_err(), dev_warn(), dev_info(), y así sucesivamente. Para mensajes que
926 no están asociados con un dispositivo particular, <linux/printk.h> define
927 pr_notice(), pr_info(), pr_warn(), pr_err(), etc.
928
929 Crear buenos mensajes de depuración puede ser todo un desafío; y una vez
930 los tiene, pueden ser de gran ayuda para la resolución remota de problemas.
931 Sin embargo, la impresión de mensajes de depuración se maneja de manera
932 diferente a la impresión de otros mensajes que no son de depuración.
933 Mientras que las otras funciones pr_XXX() se imprimen incondicionalmente,
934 pr_debug() no lo hace; se compila fuera por defecto, a menos que DEBUG sea
935 definido o se establezca CONFIG_DYNAMIC_DEBUG. Eso es cierto para dev_dbg()
936 también, y una convención relacionada usa VERBOSE_DEBUG para agregar
937 mensajes dev_vdbg() a los ya habilitados por DEBUG.
938
939 Muchos subsistemas tienen opciones de depuración de Kconfig para activar
940 -DDEBUG en el Makefile correspondiente; en otros casos, los archivos
941 usan #define DEBUG. Y cuando un mensaje de depuración debe imprimirse
942 incondicionalmente, por ejemplo si es ya dentro de una sección #ifdef
943 relacionada con la depuración, printk(KERN_DEBUG ...) puede ser usado.
944
945 14) Reservando memoria
946 ----------------------
947
948 El kernel proporciona los siguientes asignadores de memoria de propósito
949 general: kmalloc(), kzalloc(), kmalloc_array(), kcalloc(), vmalloc() y
950 vzalloc(). Consulte la documentación de la API para obtener más información.
951 a cerca de ellos. :ref:`Documentation/core-api/memory-allocation.rst
952 <memory_allocation>`
953
954 La 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
960 La forma alternativa donde se deletrea el nombre de la estructura perjudica
961 la legibilidad, y presenta una oportunidad para un error cuando se cambia
962 el tipo de variable de puntero, pero el tamaño correspondiente de eso que
963 se pasa a un asignador de memoria no.
964
965 Convertir el valor devuelto, que es un puntero vacío, es redundante. La
966 conversión desde el puntero vacío a cualquier otro tipo de puntero está
967 garantizado por la programación en idioma C.
968
969 La forma preferida para asignar una matriz es la siguiente:
970
971 .. code-block:: c
972
973 p = kmalloc_array(n, sizeof(...), ...);
974
975 La forma preferida para asignar una matriz a cero es la siguiente:
976
977 .. code-block:: c
978
979 p = kcalloc(n, sizeof(...), ...);
980
981 Ambos casos verifican el desbordamiento en el tamaño de asignación n *
982 sizeof (...), y devuelven NULL si esto ocurrió.
983
984 Todas 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
986 que no sirve de nada emitir un mensaje de fallo adicional cuando se
987 devuelva NULL.
988
989 15) La enfermedad de inline
990 ----------------------------
991
992 Parece haber una común percepción errónea de que gcc tiene una magica
993 opción "hazme más rápido" de aceleración, llamada ``inline`` (en línea).
994 Mientras que el uso de inlines puede ser apropiado (por ejemplo, como un
995 medio para reemplazar macros, consulte el Capítulo 12), muy a menudo no lo
996 es. El uso abundante de la palabra clave inline conduce a una mayor kernel,
997 que a su vez ralentiza el sistema en su conjunto, debido a una mayor huella
998 de icache para la CPU, y sencillamente porque hay menos memoria disponible
999 para el pagecache. Solo piense en esto; un fallo en la memoria caché de la
1000 página provoca una búsqueda de disco, que tarda fácilmente 5 milisegundos.
1001 Hay MUCHOS ciclos de CPU que puede entrar en estos 5 milisegundos.
1002
1003 Una razonable regla general es no poner funciones inline que tengan más de
1004 3 líneas de código en ellas. Una excepción a esta regla son los casos en
1005 que se sabe que un parámetro es una constante en tiempo de compilación, y
1006 como resultado de esto, usted *sabe*, el compilador podrá optimizar la
1007 mayor parte de su función en tiempo de compilación. Para un buen ejemplo de
1008 este último caso, véase la función en línea kmalloc().
1009
1010 A menudo, la gente argumenta que agregar funciones en línea que son
1011 estáticas y se usan solo una vez, es siempre una victoria ya que no hay
1012 perdida de espacio. Mientras esto es técnicamente correcto, gcc es capaz de
1013 incorporarlos automáticamente sin ayuda, y esta el problema de
1014 mantenimiento de eliminar el inline, cuando un segundo usuario supera el
1015 valor potencial de la pista que le dice a gcc que haga algo que habría
1016 hecho de todos modos.
1017
1018 16) Valores devueltos por función y sus nombres
1019 -----------------------------------------------
1020
1021 Las funciones pueden devolver valores de muchos tipos diferentes, y uno de
1022 lo más común es un valor que indica si la función tuvo éxito o ha fallado.
1023 Dicho 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
1025 de cero = éxito).
1026
1027 La mezcla de estos dos tipos de representaciones es una fuente fértil de
1028 errores difíciles de encontrar. Si el lenguaje C incluyera una fuerte
1029 distinción entre enteros y booleanos, el compilador encontraría estos
1030 errores por nosotros... pero no lo hace. Para ayudar a prevenir tales
1031 errores, 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
1037 Por ejemplo, ``agregar trabajo`` es un comando, y la función
1038 agregar_trabajo() devuelve 0 en caso de éxito o -EBUSY en caso de fracaso.
1039 De la misma manera, ``dispositivo PCI presente`` es un predicado, y la
1040 función pci_dev_present() devuelve 1 si tiene éxito en encontrar un
1041 dispositivo coincidente o 0 si no es así.
1042
1043 Todas las funciones EXPORTed (exportadas) deben respetar esta convención,
1044 al igual que todas las funciones publicas. Las funciones privadas
1045 (estáticas) no lo necesitan, pero es recomendado que lo hagan.
1046
1047 Las funciones cuyo valor devuelto es el resultado real de un cálculo, en
1048 lugar de una indicación de si el cómputo tuvo éxito, no están sujetas a
1049 esta regla. Generalmente indican fallo al devolver valores fuera del rango
1050 de resultados. Los ejemplos típicos serían funciones que devuelven
1051 punteros; estos usan NULL o el mecanismo ERR_PTR para informar de fallos.
1052
1053 17) Usando bool
1054 ----------------
1055
1056 El tipo bool del kernel Linux es un alias para el tipo C99 _Bool. Los
1057 valores booleanos pueden solo evaluar a 0 o 1, y la conversión implícita o
1058 explícita a bool convierte automáticamente el valor en verdadero o falso.
1059 Cuando se utilizan tipos booleanos,
1060 !! no se necesita construcción, lo que elimina una clase de errores.
1061
1062 Cuando se trabaja con valores booleanos, se deben usar las definiciones
1063 verdadera y falsa, en lugar de 1 y 0.
1064
1065 Los tipos de devolución de función bool y las variables de pila siempre
1066 se pueden usar cuando esto sea adecuado. Se recomienda el uso de bool para
1067 mejorar la legibilidad y, a menudo, es una mejor opción que 'int' para
1068 almacenar valores booleanos.
1069
1070 No use bool si el diseño de la línea de caché o el tamaño del valor son
1071 importantes, ya que su tamaño y la alineación varía según la arquitectura
1072 compilada. Las estructuras que son optimizadas para la alineación y el
1073 tamaño no debe usar bool.
1074
1075 Si una estructura tiene muchos valores verdadero/falso, considere
1076 consolidarlos en un bitfield con miembros de 1 bit, o usando un tipo de
1077 ancho fijo apropiado, como u8.
1078
1079 De manera similar, para los argumentos de función, se pueden consolidar
1080 muchos 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
1082 sitios de llamada tienen constantes desnudas de tipo verdaderas/falsas.
1083
1084 De lo contrario, el uso limitado de bool en estructuras y argumentos puede
1085 mejorar la legibilidad.
1086
1087 18) No reinvente las macros del kernel
1088 ---------------------------------------
1089
1090 El archivo de cabecera include/linux/kernel.h contiene una serie de macros
1091 que debe usar, en lugar de programar explícitamente alguna variante de
1092 estos por usted mismo. Por ejemplo, si necesita calcular la longitud de una
1093 matriz, aproveche la macro
1094
1095 .. code-block:: c
1096
1097 #define ARRAY_SIZE(x) (sizeof(x) / sizeof((x)[0]))
1098
1099 De manera similar, si necesita calcular el tamaño de algún miembro de la
1100 estructura, use
1101
1102 .. code-block:: c
1103
1104 #define sizeof_field(t, f) (sizeof(((t*)0)->f))
1105
1106 También hay macros min() y max() que realizan una verificación estricta de
1107 tipos si lo necesita. Siéntase libre de leer detenidamente ese archivo de
1108 encabezado para ver qué más ya está definido y que no debe reproducir en su
1109 código.
1110
1111 19) Editores modeline y otros desastres
1112 ---------------------------------------
1113
1114 Algunos editores pueden interpretar la información de configuración
1115 incrustada en los archivos fuente, indicado con marcadores especiales. Por
1116 ejemplo, emacs interpreta las líneas marcadas como esto:
1117
1118 .. code-block:: c
1119
1120 -*- mode: c -*-
1121
1122 O así:
1123
1124 .. code-block:: c
1125
1126 /*
1127 Local Variables:
1128 compile-command: "gcc -DMAGIC_DEBUG_FLAG foo.c"
1129 End:
1130 */
1131
1132 Vim interpreta los marcadores que se ven así:
1133
1134 .. code-block:: c
1135
1136 /* vim:set sw=8 noet */
1137
1138 No incluya ninguno de estos en los archivos fuente. La gente tiene sus
1139 propias configuraciones del editor, y sus archivos de origen no deben
1140 anularlos. Esto incluye marcadores para sangría y configuración de modo.
1141 La gente puede usar su propio modo personalizado, o puede tener algún otro
1142 método mágico para que la sangría funcione correctamente.
1143
1144
1145 20) Ensamblador inline
1146 -----------------------
1147
1148 En el código específico de arquitectura, es posible que deba usar
1149 ensamblador en línea para interactuar con funcionalidades de CPU o
1150 plataforma. No dude en hacerlo cuando sea necesario. Sin embargo, no use
1151 ensamblador en línea de forma gratuita cuando C puede hacer el trabajo.
1152 Puede y debe empujar el hardware desde C cuando sea posible.
1153
1154 Considere escribir funciones auxiliares simples que envuelvan bits comunes
1155 de ensamblador, en lugar de escribirlos repetidamente con ligeras
1156 variaciones. Recuerde que el ensamblador en línea puede usar parámetros C.
1157
1158 Las funciones de ensamblador grandes y no triviales deben ir en archivos .S,
1159 con su correspondientes prototipos de C definidos en archivos de encabezado
1160 en C. Los prototipos de C para el ensamblador deben usar ``asmlinkage``.
1161
1162 Es posible que deba marcar su declaración asm como volátil, para evitar que
1163 GCC la elimine si GCC no nota ningún efecto secundario. No siempre es
1164 necesario hacerlo, sin embargo, y hacerlo innecesariamente puede limitar la
1165 optimización.
1166
1167 Al escribir una sola declaración de ensamblador en línea que contiene
1168 múltiples instrucciones, ponga cada instrucción en una línea separada en
1169 una string separada, y termine cada string excepto la última con ``\n\t``
1170 para indentar correctamente la siguiente instrucción en la salida en
1171 ensamblador:
1172
1173 .. code-block:: c
1174
1175 asm ("magic %reg1, #42\n\t"
1176 "more_magic %reg2, %reg3"
1177 : /* outputs */ : /* inputs */ : /* clobbers */);
1178
1179 21) Compilación condicional
1180 ---------------------------
1181
1182 Siempre 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
1184 la lógica más difícil de seguir. En cambio, use dichos condicionales en un
1185 archivo de encabezado que defina funciones para usar en esos archivos .c,
1186 proporcionando versiones de código auxiliar sin operación en el caso #else,
1187 y luego llame a estas funciones incondicionalmente desde archivos .c. El
1188 compilador evitará generar cualquier código para las llamadas restantes,
1189 produciendo resultados idénticos, pero la lógica es fácil de seguir.
1190
1191 Prefiera compilar funciones completas, en lugar de porciones de funciones o
1192 porciones de expresiones. En lugar de poner un ifdef en una expresión,
1193 divida la totalidad de la expresión con una función de ayuda independiente
1194 y aplique el condicional a esa función.
1195
1196 Si tiene una función o variable que puede potencialmente quedar sin usar en
1197 una configuración en particular, y el compilador advertiría sobre su
1198 definición sin usar, marque la definición como __maybe_unused en lugar de
1199 envolverla en un preprocesador condicional. (Sin embargo, si una función o
1200 variable *siempre* acaba sin ser usada, bórrela.)
1201
1202 Dentro del código, cuando sea posible, use la macro IS_ENABLED para
1203 convertir un símbolo Kconfig en una expresión booleana de C, y utilícelo en
1204 un condicional de C normal:
1205
1206 .. code-block:: c
1207
1208 if (IS_ENABLED(CONFIG_SOMETHING)) {
1209 ...
1210 }
1211
1212 El compilador "doblará"" constantemente el condicional e incluirá o
1213 excluirá el bloque de código al igual que con un #ifdef, por lo que esto no
1214 agregará ningún tiempo de gastos generales en ejecución. Sin embargo, este
1215 enfoque todavía permite que el compilador de C vea el código dentro del
1216 bloque, y verifique que sea correcto (sintaxis, tipos, símbolo, referencias,
1217 etc.). Por lo tanto, aún debe usar un #ifdef si el código dentro del bloque
1218 hace referencia a símbolos que no existirán si no se cumple la condición.
1219
1220 Al final de cualquier bloque #if o #ifdef no trivial (más de unas pocas
1221 líneas), incluya un comentario después de #endif en la misma línea,
1222 anotando la expresión condicional utilizada. Por ejemplo:
1223
1224 .. code-block:: c
1225
1226 #ifdef CONFIG_SOMETHING
1227 ...
1228 #endif /* CONFIG_SOMETHING */
1229
1230 22) No rompa el kernel
1231 -----------------------
1232
1233 En general, la decisión de romper el kernel pertenece al usuario, más que
1234 al desarrollador del kernel.
1235
1236 Evite el panic()
1237 ****************
1238
1239 panic() debe usarse con cuidado y principalmente solo durante el arranque
1240 del sistema. panic() es, por ejemplo, aceptable cuando se queda sin memoria
1241 durante el arranque y no puede continuar.
1242
1243 Use WARN() en lugar de BUG()
1244 ****************************
1245
1246 No agregue código nuevo que use cualquiera de las variantes BUG(), como
1247 BUG(), BUG_ON() o VM_BUG_ON(). En su lugar, use una variante WARN*(),
1248 preferiblemente WARN_ON_ONCE(), y posiblemente con código de recuperación.
1249 El código de recuperación no es requerido si no hay una forma razonable de
1250 recuperar, al menos parcialmente.
1251
1252 "Soy demasiado perezoso para tener en cuenta los errores" no es una excusa
1253 para usar BUG(). Importantes corrupciones internas sin forma de continuar
1254 aún pueden usar BUG(), pero necesitan una buena justificación.
1255
1256 Use WARN_ON_ONCE() en lugar de WARN() o WARN_ON()
1257 *************************************************
1258
1259 Generalmente, se prefiere WARN_ON_ONCE() a WARN() o WARN_ON(), porque es
1260 común que una condición de advertencia dada, si ocurre, ocurra varias
1261 veces. Esto puede llenar el registro del kernel, e incluso puede ralentizar
1262 el sistema lo suficiente como para que el registro excesivo se convierta en
1263 su propio, adicional problema.
1264
1265 No haga WARN a la ligera
1266 ************************
1267
1268 WARN*() está diseñado para situaciones inesperadas que nunca deberían
1269 suceder. Las macros WARN*() no deben usarse para nada que se espera que
1270 suceda durante un funcionamiento normal. No hay "checkeos" previos o
1271 posteriores a la condición, por ejemplo. De nuevo: WARN*() no debe usarse
1272 para una condición esperada que vaya a activarse fácilmente, por ejemplo,
1273 mediante acciones en el espacio del usuario. pr_warn_once() es una
1274 alternativa posible, si necesita notificar al usuario de un problema.
1275
1276 No se preocupe sobre panic_on_warn de usuarios
1277 **********************************************
1278
1279 Algunas palabras más sobre panic_on_warn: Recuerde que ``panic_on_warn`` es
1280 una opción disponible del kernel, y que muchos usuarios configuran esta
1281 opción. Esta es la razón por la que hay un artículo de "No haga WARN a la
1282 ligera", arriba. Sin embargo, la existencia de panic_on_warn de usuarios no
1283 es una razón válida para evitar el uso juicioso de WARN*(). Esto se debe a
1284 que quien habilita panic_on_warn, explícitamente pidió al kernel que
1285 fallara si se dispara un WARN*(), y tales usuarios deben estar preparados
1286 para afrontar las consecuencias de un sistema que es algo más probable que
1287 se rompa.
1288
1289 Use BUILD_BUG_ON() para aserciones en tiempo de compilación
1290 ***********************************************************
1291
1292 El uso de BUILD_BUG_ON() es aceptable y recomendado, porque es una aserción
1293 en tiempo de compilación, que no tiene efecto en tiempo de ejecución.
1294
1295 Apéndice I) Referencias
1296 -----------------------
1297
1298 The C Programming Language, Segunda edicion
1299 por Brian W. Kernighan and Dennis M. Ritchie.
1300 Prentice Hall, Inc., 1988.
1301 ISBN 0-13-110362-8 (paperback), 0-13-110370-9 (hardback).
1302
1303 The Practice of Programming
1304 por Brian W. Kernighan and Rob Pike.
1305 Addison-Wesley, Inc., 1999.
1306 ISBN 0-201-61586-X.
1307
1308 manuales GCC - en cumplimiento con K&R y este texto - para cpp, gcc,
1309 detalles de gcc y sangría, todo disponible en https://www.gnu.org/manual/
1310
1311 WG14 es el grupo de trabajo de estandarización internacional de la
1312 programació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:
1315 http://www.kroah.com/linux/talks/ols_2002_kernel_codingstyle_talk/html/
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.