summaryrefslogtreecommitdiff
path: root/Documentation/translations/sp_SP/process/coding-style.rst
blob: a37274764371199862d36f41915161c428899b23 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
.. include:: ../disclaimer-sp.rst

:Original: :ref:`Documentation/process/coding-style.rst <submittingpatches>`
:Translator: Carlos Bilbao <carlos.bilbao@amd.com>

.. _sp_codingstyle:

Estilo en el código del kernel Linux
=====================================

Este es un breve documento que describe el estilo preferido en el código
del kernel Linux. El estilo de código es muy personal y no **forzaré** mi
puntos de vista sobre nadie, pero esto vale para todo lo que tengo que
mantener, y preferiría que para la mayoría de otras cosas también. Por
favor, por lo menos considere los argumentos expuestos aquí.

En primer lugar, sugeriría imprimir una copia de los estándares de código
GNU, y NO leerlo. Quémelos, es un gran gesto simbólico.

De todos modos, aquí va:


1) Sangría
-----------

Las tabulaciones tienen 8 caracteres y, por lo tanto, las sangrías también
tienen 8 caracteres. Hay movimientos heréticos que intentan hacer sangría
de 4 (¡o incluso 2!) caracteres de longitud, y eso es similar a tratar de
definir el valor de PI como 3.

Justificación: La idea detrás de la sangría es definir claramente dónde
comienza y termina un bloque de control. Especialmente, cuando ha estado
buscando en su pantalla durante 20 horas seguidas, le resultará mucho más
fácil ver cómo funciona la sangría si tiene sangrías grandes.

Bueno, algunas personas dirán que tener sangrías de 8 caracteres hace que
el código se mueva demasiado a la derecha y dificulta la lectura en una
pantalla de terminal de 80 caracteres. La respuesta a eso es que si
necesita más de 3 niveles de sangría, está en apuros de todos modos y
debería arreglar su programa.

En resumen, las sangrías de 8 caracteres facilitan la lectura y tienen la
ventaja añadida de advertirle cuando está anidando sus funciones demasiado
profundo. Preste atención a esa advertencia.

La forma preferida de facilitar múltiples niveles de sangría en una
declaración de switch es para alinear el ``switch`` y sus etiquetas
``case`` subordinadas en la misma columna, en lugar de hacer ``doble
sangría`` (``double-indenting``) en etiquetas ``case``. Por ejemplo:

.. code-block:: c

	switch (suffix) {
	case 'G':
	case 'g':
		mem <<= 30;
		break;
	case 'M':
	case 'm':
		mem <<= 20;
		break;
	case 'K':
	case 'k':
		mem <<= 10;
		fallthrough;
	default:
		break;
	}

No ponga varias declaraciones en una sola línea a menos que tenga algo que
ocultar:

.. code-block:: c

	if (condición) haz_esto;
	  haz_otra_cosa;

No use comas para evitar el uso de llaves:

.. code-block:: c

	if (condición)
		haz_esto(), haz_eso();

Siempre use llaves para múltiples declaraciones:

.. code-block:: c

	if (condición) {
		haz_esto();
		haz_eso();
	}

Tampoco ponga varias asignaciones en una sola línea. El estilo de código
del kernel es súper simple. Evite las expresiones engañosas.


Aparte de los comentarios, la documentación y excepto en Kconfig, los
espacios nunca se utilizan para la sangría, y el ejemplo anterior se rompe
deliberadamente.

Consiga un editor decente y no deje espacios en blanco al final de las
líneas.

2) Rompiendo líneas y strings largos
------------------------------------

El estilo de código tiene todo que ver con la legibilidad y la
mantenibilidad usando herramientas disponibles comúnmente.

El límite preferido en la longitud de una sola línea es de 80 columnas.

Las declaraciones de más de 80 columnas deben dividirse en partes, a menos
que exceder las 80 columnas aumente significativamente la legibilidad y no
oculte información.

Los descendientes siempre son sustancialmente más cortos que el padre y
se colocan sustancialmente a la derecha. Un estilo muy usado es alinear
descendientes a un paréntesis de función abierto.

Estas mismas reglas se aplican a los encabezados de funciones con una larga
lista de argumentos.

Sin embargo, nunca rompa los strings visibles para el usuario, como los
mensajes printk, porque eso rompe la capacidad de grep a estos.


3) Colocación de llaves y espacios
----------------------------------

El otro problema que siempre surge en el estilo C es la colocación de
llaves. A diferencia del tamaño de la sangría, existen pocas razones
técnicas para elegir una estrategia de ubicación sobre la otra, pero la
forma preferida, como mostraron los profetas Kernighan y Ritchie, es poner
la llave de apertura en la línea, y colocar la llave de cierre primero,
así:

.. code-block:: c

	if (x es verdad) {
		hacemos y
	}

Esto se aplica a todos los bloques de declaraciones que no son funciones
(if, switch, for, while, do). Por ejemplo:

.. code-block:: c

	switch (action) {
	case KOBJ_ADD:
		return "add";
	case KOBJ_REMOVE:
		return "remove";
	case KOBJ_CHANGE:
		return "change";
	default:
		return NULL;
	}

Sin embargo, hay un caso especial, a saber, las funciones: tienen la llave
de apertura al comienzo de la siguiente línea, así:

.. code-block:: c

	int funcion(int x)
	{
		cuerpo de la función
	}

Gente hereje de todo el mundo ha afirmado que esta inconsistencia es...
bueno... inconsistente, pero todas las personas sensatas saben que
(a) K&R tienen **razón** y (b) K&R tienen razón. Además, las funciones son
especiales de todos modos (no puede anidarlas en C).

Tenga en cuenta que la llave de cierre está vacía en su línea propia,
**excepto** en los casos en que es seguida por una continuación de la misma
declaración, es decir, un ``while`` en una sentencia do o un ``else`` en
una sentencia if, como en:

.. code-block:: c

	do {
		cuerpo del bucle do
	} while (condition);

y

.. code-block:: c

	if (x == y) {
		..
	} else if (x > y) {
		...
	} else {
		....
	}

Justificación: K&R.

Además, tenga en cuenta que esta colocación de llaves también minimiza el
número de líneas vacías (o casi vacías), sin pérdida de legibilidad. Así,
como el suministro de nuevas líneas en su pantalla no es un recurso
renovable (piense en pantallas de terminal de 25 líneas), tienes más líneas
vacías para poner comentarios.

No use llaves innecesariamente donde una sola declaración sea suficiente.

.. code-block:: c

	if (condition)
		accion();

y

.. code-block:: none

	if (condición)
		haz_esto();
	else
		haz_eso();

Esto no aplica si solo una rama de una declaración condicional es una sola
declaración; en este último caso utilice llaves en ambas ramas:

.. code-block:: c

	if (condición) {
		haz_esto();
		haz_eso();
	} else {
		en_otro_caso();
	}

Además, use llaves cuando un bucle contenga más de una declaración simple:

.. code-block:: c

	while (condición) {
		if (test)
			haz_eso();
	}

3.1) Espacios
*************

El estilo del kernel Linux para el uso de espacios depende (principalmente)
del uso de función versus uso de palabra clave. Utilice un espacio después
de (la mayoría de) las palabras clave. Las excepciones notables son sizeof,
typeof, alignof y __attribute__, que parecen algo así como funciones (y
generalmente se usan con paréntesis en Linux, aunque no son requeridos en
el idioma, como en: ``sizeof info`` después de que ``struct fileinfo info;``
se declare).

Así que use un espacio después de estas palabras clave::

	if, switch, case, for, do, while

pero no con sizeof, typeof, alignof, o __attribute__. Por ejemplo,

.. code-block:: c


	s = sizeof(struct file);

No agregue espacios alrededor (dentro) de expresiones entre paréntesis.
Este ejemplo es **malo**:

.. code-block:: c


	s = sizeof( struct file );

Al declarar datos de puntero o una función que devuelve un tipo de puntero,
el uso preferido de ``*`` es adyacente al nombre del dato o nombre de la
función y no junto al nombre del tipo. Ejemplos:

.. code-block:: c


	char *linux_banner;
	unsigned long long memparse(char *ptr, char **retptr);
	char *match_strdup(substring_t *s);

Use un espacio alrededor (a cada lado de) la mayoría de los operadores
binarios y ternarios, como cualquiera de estos::

	=  +  -  <  >  *  /  %  |  &  ^  <=  >=  ==  !=  ?  :

pero sin espacio después de los operadores unarios::

	&  *  +  -  ~  !  sizeof  typeof  alignof  __attribute__  defined

sin espacio antes de los operadores unarios de incremento y decremento del
sufijo::

	++  --

y sin espacio alrededor de los operadores de miembros de estructura ``.`` y
``->``.

No deje espacios en blanco al final de las líneas. Algunos editores con
``inteligente`` sangría insertarán espacios en blanco al comienzo de las
nuevas líneas como sea apropiado, para que pueda comenzar a escribir la
siguiente línea de código de inmediato. Sin embargo, algunos de estos
editores no eliminan los espacios en blanco si finalmente no termina
poniendo una línea de código allí, como si dejara una línea en blanco. Como
resultado, termina con líneas que contienen espacios en blanco al final.

Git le advertirá sobre los parches que introducen espacios en blanco al
final y puede, opcionalmente, eliminar los espacios en blanco finales por
usted; sin embargo, si se aplica una serie de parches, esto puede hacer que
los parches posteriores de la serie fallen al cambiar sus líneas de
contexto.


4) Nomenclatura
---------------

C es un lenguaje espartano, y sus convenciones de nomenclatura deberían
seguir su ejemplo. A diferencia de los programadores de Modula-2 y Pascal,
los programadores de C no usan nombres cuquis como
EstaVariableEsUnContadorTemporal. Un programador de C lo llamaría
variable ``tmp``, que es mucho más fácil de escribir, y no es mas difícil
de comprender.

SIN EMBARGO, mientras que los nombres de mayúsculas y minúsculas están mal
vistos, los nombres descriptivos para las variables globales son
imprescindibles. Llamar a una función global ``foo`` es un delito.

Una variable GLOBAL (para usar solo si **realmente** las necesita) necesita
tener un nombre descriptivo, al igual que las funciones globales. Si tiene
una función que cuenta el número de usuarios activos, debe llamar a esta
``contar_usuarios_activos()`` o similar, **no** debe llamarlo ``cntusr()``.

Codificar el tipo de una función en el nombre (lo llamado notación húngara)
es estúpido: el compilador conoce los tipos de todos modos y puede
verificar estos, y solo confunde al programador.

Los nombres de las variables LOCALES deben ser breves y directos. Si usted
tiene algún contador aleatorio de tipo entero, probablemente debería
llamarse ``i``. Llamarlo ``loop_counter`` no es productivo, si no hay
posibilidad de ser mal entendido. De manera similar, ``tmp`` puede ser casi
cualquier tipo de variable que se utiliza para contener un valor temporal.

Si tiene miedo de mezclar los nombres de las variables locales, tiene otro
problema, que se denomina síndrome de
función-crecimiento-desequilibrio-de-hormona. Vea el capítulo 6 (Funciones).

Para nombres de símbolos y documentación, evite introducir nuevos usos de
'master / slave' (maestro / esclavo) (o 'slave' independientemente de
'master') y 'lista negra / lista blanca' (backlist / whitelist).

Los reemplazos recomendados para 'maestro / esclavo' son:
    '{primary,main} / {secondary,replica,subordinate}'
    '{initiator,requester} / {target,responder}'
    '{controller,host} / {device,worker,proxy}'
    'leader / follower'
    'director / performer'

Los reemplazos recomendados para 'backlist / whitelist' son:
    'denylist / allowlist'
    'blocklist / passlist'

Las excepciones para la introducción de nuevos usos son mantener en espacio
de usuario una ABI/API, o al actualizar la especificación del código de un
hardware o protocolo existente (a partir de 2020) que requiere esos
términos. Para nuevas especificaciones, traduzca el uso de la terminología
de la especificación al estándar de código del kernel donde sea posible.

5) Typedefs
-----------

Por favor no use cosas como ``vps_t``.
Es un **error** usar typedef para estructuras y punteros. cuando ve un

.. code-block:: c


	vps_t a;

en el código fuente, ¿qué significa?
En cambio, si dice

.. code-block:: c

	struct virtual_container *a;

puede decir qué es ``a`` en realidad.

Mucha gente piensa que  los typedefs ``ayudan a la legibilidad``. No. Son
útiles solamente para:

 (a) objetos totalmente opacos (donde el typedef se usa activamente para
     **ocultar** cuál es el objeto).

     Ejemplo: ``pte_t`` etc. objetos opacos a los que solo puede acceder
     usando las funciones de acceso adecuadas.

     .. note::

       La opacidad y las ``funciones de acceso`` no son buenas por sí
       mismas. La razón por la que los tenemos para cosas como pte_t, etc.
       es que hay real y absolutamente **cero** información accesible de
       forma portátil allí.

 (b) Tipos enteros claros, donde la abstracción **ayuda** a evitar
     confusiones, ya sea ``int`` o ``long``.

     u8/u16/u32 son definiciones tipográficas perfectamente correctas
     aunque encajan en la categoría (d) mejor que aquí.

     .. note::

       De nuevo - debe haber una **razón** para esto. si algo es
       ``unsigned long``, entonces no hay razón para hacerlo

	typedef unsigned long mis_flags_t;

     pero si hay una razón clara de por qué bajo ciertas circunstancias
     podría ser un ``unsigned int`` y bajo otras configuraciones podría
     ser ``unsigned long``, entonces, sin duda, adelante y use un typedef.

 (c) cuando lo use para crear literalmente un tipo **nuevo** para
     comprobación de tipos.

 (d) Nuevos tipos que son idénticos a los tipos estándar C99, en ciertas
     circunstancias excepcionales.

     Aunque sólo costaría un corto período de tiempo para los ojos y
     cerebro para acostumbrarse a los tipos estándar como ``uint32_t``,
     algunas personas se oponen a su uso de todos modos.

     Por lo tanto, los tipos ``u8/u16/u32/u64`` específicos de Linux y sus
     equivalentes con signo, que son idénticos a los tipos estándar son
     permitidos, aunque no son obligatorios en el nuevo código de su
     elección.

     Al editar código existente que ya usa uno u otro conjunto de tipos,
     debe ajustarse a las opciones existentes en ese código.

 (e) Tipos seguros para usar en el espacio de usuario.

     En ciertas estructuras que son visibles para el espacio de usuario, no
     podemos requerir tipos C99 y o utilizat el ``u32`` anterior. Por lo
     tanto, usamos __u32 y tipos similares en todas las estructuras que se
     comparten con espacio de usuario.

Tal vez también haya otros casos, pero la regla básicamente debería ser
NUNCA JAMÁS use un typedef a menos que pueda coincidir claramente con una
de estas reglas.

En general, un puntero o una estructura que tiene elementos que pueden
ser razonablemente accedidos directamente, **nunca** deben ser un typedef.

6) Funciones
------------

Las funciones deben ser cortas y dulces, y hacer una sola cosa. Deberían
caber en una o dos pantallas de texto (el tamaño de pantalla ISO/ANSI es
80x24, como todos sabemos), y hacer una cosa y hacerla bien.

La longitud máxima de una función es inversamente proporcional a la
complejidad y el nivel de sangría de esa función. Entonces, si tiene una
función conceptualmente simple que es solo una larga (pero simple)
declaración de case, donde tiene que hacer un montón de pequeñas cosas para
un montón de diferentes casos, está bien tener una función más larga.

Sin embargo, si tiene una función compleja y sospecha que un estudiante de
primer año de secundaria menos que dotado podría no comprender de qué se
trata la función, debe adherirse a los límites máximos tanto más de
cerca. Use funciones auxiliares con nombres descriptivos (puede pedirle al
compilador que los alinee si cree que es crítico para el rendimiento, y
probablemente lo hará mejor de lo que usted hubiera hecho).

Otra medida de la función es el número de variables locales. Estas no deben
exceder de 5 a 10, o está haciendo algo mal. Piense de nuevo en la función
y divida en partes más pequeñas. Un cerebro humano puede generalmente
realiza un seguimiento de aproximadamente 7 cosas diferentes, cualquier
elemento más y se confunde. Usted sabe que es brillante, pero tal vez le
gustaría entender lo que hizo dentro de 2 semanas.

En los archivos fuente, separe las funciones con una línea en blanco. Si la
función es exportada, la macro **EXPORT** debería ponerse inmediatamente
después de la función de cierre de línea de llave. Por ejemplo:

.. code-block:: c

	int sistema_corriendo(void)
	{
		return estado_sistema == SISTEMA_CORRIENDO;
	}
	EXPORT_SYMBOL(sistema_corriendo);

6.1) Prototipos de funciones
****************************

En los prototipos de funciones, incluya nombres de parámetros con sus tipos
de datos. Aunque esto no es requerido por el lenguaje C, se prefiere en
Linux porque es una forma sencilla de añadir información valiosa para el
lector.

No utilice la palabra clave ``extern`` con declaraciones de función ya que
esto hace las líneas más largas y no es estrictamente necesario.

Al escribir prototipos de funciones, mantenga el `orden de los elementos regular
<https://lore.kernel.org/mm-commits/CAHk-=wiOCLRny5aifWNhr621kYrJwhfURsa0vFPeUEm8mF0ufg@mail.gmail.com/>`_.
Por ejemplo, usando este ejemplo de declaración de función::

 __init void * __must_check action(enum magic value, size_t size, u8 count,
				   char *fmt, ...) __printf(4, 5) __malloc;

El orden preferido de elementos para un prototipo de función es:

- clase de almacenamiento (a continuación, ``static __always_inline``,
  teniendo en cuenta que ``__always_inline`` es técnicamente un atributo
  pero se trata como ``inline``)
- atributos de clase de almacenamiento (aquí, ``__init`` -- es decir,
  declaraciones de sección, pero también cosas como ``__cold``)
- tipo de retorno (aquí, ``void *``)
- atributos de tipo de retorno (aquí, ``__must_check``)
- nombre de la función (aquí, ``action``)
- parámetros de la función (aquí, ``(enum magic value, size_t size, u8 count, char *fmt, ...)``,
  teniendo en cuenta que los nombres de los parámetros siempre deben
  incluirse)
- atributos de parámetros de función (aquí, ``__printf(4, 5)``)
- atributos de comportamiento de la función (aquí, ``__malloc``)

Tenga en cuenta que para una **definición** de función (es decir, el cuerpo
real de la función), el compilador no permite atributos de parámetros de
función después de parámetros de la función. En estos casos, deberán ir
tras los atributos de clase (por ejemplo, tenga en cuenta el cambio de
posición de ``__printf(4, 5)`` a continuación, en comparación con el
ejemplo de **declaración** anterior)::

 static __always_inline __init __printf(4, 5) void * __must_check action(enum magic value,
		size_t size, u8 count, char *fmt, ...) __malloc
 {
	...
 }

7) Salida centralizada de funciones
-----------------------------------

Aunque desaprobado por algunas personas, el equivalente de la instrucción
goto es utilizado con frecuencia por los compiladores, en forma de
instrucción de salto incondicional.

La declaración goto es útil cuando una función sale desde múltiples
ubicaciones y se deben realizar algunos trabajos comunes, como la limpieza.
Si no se necesita limpieza, entonces simplemente haga return directamente.

Elija nombres de etiquetas que digan qué hace el goto o por qué existe el
goto. Un ejemplo de un buen nombre podría ser ``out_free_buffer:``
(``salida_liberar_buffer``) si al irse libera ``buffer``. Evite usar
nombres GW-BASIC como ``err1:`` y ``err2:``, ya que tendría que volver a
numerarlos si alguna vez agrega o elimina rutas de salida, y hacen que sea
difícil de verificar que sean correctos, de todos modos.

La razón para usar gotos es:

- Las declaraciones incondicionales son más fáciles de entender y seguir.
- se reduce el anidamiento
- errores al no actualizar los puntos de salida individuales al hacer
  modificaciones son evitados
- ahorra el trabajo del compilador de optimizar código redundante ;)

.. code-block:: c

	int fun(int a)
	{
		int result = 0;
		char *buffer;

		buffer = kmalloc(SIZE, GFP_KERNEL);
		if (!buffer)
			return -ENOMEM;

		if (condition1) {
			while (loop1) {
				...
			}
			result = 1;
			goto out_free_buffer;
		}
		...
	out_free_buffer:
		kfree(buffer);
		return result;
	}

Un tipo común de error a tener en cuenta es "un error de error" que es algo
así:

.. code-block:: c

	err:
		kfree(foo->bar);
		kfree(foo);
		return ret;

El error en este código es que en algunas rutas de salida, ``foo`` es NULL.
Normalmente la solución para esto es dividirlo en dos etiquetas de error
``err_free_bar:`` y ``err_free_foo:``:

.. code-block:: c

	err_free_bar:
		kfree(foo->bar);
	err_free_foo:
		kfree(foo);
		return ret;

Idealmente, debería simular errores para probar todas las rutas de salida.


8) Comentarios
--------------

Los comentarios son buenos, pero también existe el peligro de comentar
demasiado. NUNCA trate de explicar CÓMO funciona su código en un
comentario: es mucho mejor escribir el código para que el
**funcionamiento** sea obvio y es una pérdida de tiempo explicar código mal
escrito.

Generalmente, desea que sus comentarios digan QUÉ hace su código, no CÓMO.
Además, trate de evitar poner comentarios dentro del cuerpo de una función:
si la función es tan compleja que necesita comentar por separado partes de
esta, probablemente debería volver al capítulo 6 una temporada. Puede
hacer pequeños comentarios para notar o advertir sobre algo particularmente
inteligente (o feo), pero trate de evitar el exceso. En su lugar, ponga los
comentarios al principio de la función, diga a la gente lo que hace y
posiblemente POR QUÉ hace esto.

Al comentar las funciones de la API del kernel, utilice el formato
kernel-doc. Consulte los archivos en :ref:`Documentation/doc-guide/ <doc_guide>`
y ``scripts/kernel-doc`` para más detalles.

El estilo preferido para comentarios largos (de varias líneas) es:

.. code-block:: c

	/*
	* Este es el estilo preferido para comentarios
	* multilínea en el código fuente del kernel Linux.
	* Por favor, utilícelo constantemente.
	*
	* Descripción: Una columna de asteriscos en el lado izquierdo,
	* con líneas iniciales y finales casi en blanco.
	*/

Para archivos en net/ y drivers/net/, el estilo preferido para comentarios
largos (multi-linea) es un poco diferente.

.. code-block:: c

	/* El estilo de comentario preferido para archivos en net/ y drivers/net
	* se asemeja a esto.
	*
	* Es casi lo mismo que el estilo de comentario generalmente preferido,
	* pero no hay una línea inicial casi en blanco.
	*/

También es importante comentar los datos, ya sean tipos básicos o
derivados. Para este fin, use solo una declaración de datos por línea (sin
comas para múltiples declaraciones de datos). Esto le deja espacio para un
pequeño comentario sobre cada elemento, explicando su uso.

9) Has hecho un desastre
---------------------------

Está bien, todos lo hacemos. Probablemente un antiguo usuario de Unix le
haya dicho que ``GNU emacs`` formatea automáticamente las fuentes C por
usted, y ha notado que sí, lo hace, pero los por defecto que tiene son
menos que deseables (de hecho, son peores que los aleatorios) escribiendo -
un número infinito de monos escribiendo en GNU emacs nunca harán un buen
programa).

Por lo tanto, puede deshacerse de GNU emacs o cambiarlo y usar valores más
sanos. Para hacer esto último, puede pegar lo siguiente en su archivo
.emacs:

.. code-block:: none

  (defun c-lineup-arglist-tabs-only (ignored)
    "Line up argument lists by tabs, not spaces"
    (let* ((anchor (c-langelem-pos c-syntactic-element))
           (column (c-langelem-2nd-pos c-syntactic-element))
           (offset (- (1+ column) anchor))
           (steps (floor offset c-basic-offset)))
      (* (max steps 1)
         c-basic-offset)))

  (dir-locals-set-class-variables
   'linux-kernel
   '((c-mode . (
          (c-basic-offset . 8)
          (c-label-minimum-indentation . 0)
          (c-offsets-alist . (
                  (arglist-close         . c-lineup-arglist-tabs-only)
                  (arglist-cont-nonempty .
                      (c-lineup-gcc-asm-reg c-lineup-arglist-tabs-only))
                  (arglist-intro         . +)
                  (brace-list-intro      . +)
                  (c                     . c-lineup-C-comments)
                  (case-label            . 0)
                  (comment-intro         . c-lineup-comment)
                  (cpp-define-intro      . +)
                  (cpp-macro             . -1000)
                  (cpp-macro-cont        . +)
                  (defun-block-intro     . +)
                  (else-clause           . 0)
                  (func-decl-cont        . +)
                  (inclass               . +)
                  (inher-cont            . c-lineup-multi-inher)
                  (knr-argdecl-intro     . 0)
                  (label                 . -1000)
                  (statement             . 0)
                  (statement-block-intro . +)
                  (statement-case-intro  . +)
                  (statement-cont        . +)
                  (substatement          . +)
                  ))
          (indent-tabs-mode . t)
          (show-trailing-whitespace . t)
          ))))

  (dir-locals-set-directory-class
   (expand-file-name "~/src/linux-trees")
   'linux-kernel)

Esto hará que emacs funcione mejor con el estilo de código del kernel para
C en archivos bajo ``~/src/linux-trees``.

Pero incluso si no logra que emacs realice un formateo correcto, no todo
está perdido: use ``indent``.

Ahora bien, de nuevo, la sangría de GNU tiene la misma configuración de
muerte cerebral que GNU emacs tiene, por lo que necesita darle algunas
opciones de línea de comando. Sin embargo, eso no es tan malo, porque
incluso los creadores de GNU indent reconocen la autoridad de K&R (la gente
de GNU no es mala, solo están gravemente equivocados en este asunto), por
lo que simplemente de a la sangría las opciones ``-kr -i8`` (significa
``K&R, guiones de 8 caracteres``), o use ``scripts/Lindent``, que indenta
con ese estilo.

``indent`` tiene muchas opciones, y especialmente cuando se trata de
comentar reformateos, es posible que desee echar un vistazo a la página del
manual. Pero recuerde: ``indent`` no es la solución para una mala
programación.

Tenga en cuenta que también puede usar la herramienta ``clang-format`` para
ayudarlo con estas reglas, para volver a formatear rápidamente partes de su
código automáticamente, y revisar archivos completos para detectar errores
de estilo del código, errores tipográficos y posibles mejoras. También es
útil para ordenar ``#includes``, para alinear variables/macros, para
redistribuir texto y otras tareas similares. Vea el archivo
:ref:`Documentation/process/clang-format.rst <clangformat>` para más
detalles.

10) Archivos de configuración de Kconfig
----------------------------------------

Para todos los archivos de configuración de Kconfig* en todo el árbol
fuente, la sangría es algo diferente. Las líneas bajo una definición
``config`` están indentadas con una tabulación, mientras que el texto de
ayuda tiene una sangría adicional de dos espacios. Ejemplo::

  config AUDIT
	bool "Soporte para auditar"
	depends on NET
	help
	  Habilita la infraestructura de auditoría que se puede usar con otro
	  subsistema kernel, como SELinux (que requiere esto para
	  registro de salida de mensajes avc). No hace auditoría de llamadas al
    sistema sin CONFIG_AUDITSYSCALL.

Características seriamente peligrosas (como soporte de escritura para
ciertos filesystems) deben anunciar esto de forma destacada en su cadena de
solicitud::

  config ADFS_FS_RW
	bool "ADFS write support (DANGEROUS)"
	depends on ADFS_FS
	...

Para obtener la documentación completa sobre los archivos de configuración,
consulte el archivo Documentation/kbuild/kconfig-language.rst.


11) Estructuras de datos
------------------------

Las estructuras de datos que tienen visibilidad fuera del contexto de un
solo subproceso en el que son creadas y destruidas, siempre debe tener
contadores de referencia. En el kernel, la recolección de basura no existe
(y fuera, la recolección de basura del kernel es lenta e ineficiente), lo
que significa que absolutamente **tiene** para hacer referencia y contar
todos sus usos.

El conteo de referencias significa que puede evitar el bloqueo y permite
que múltiples usuarios tengan acceso a la estructura de datos en paralelo -
y no tengan que preocuparse de que la estructura, de repente, desaparezca
debajo de su control, solo porque durmieron o hicieron otra cosa por un
tiempo.

Tenga en cuenta que el bloqueo **no** reemplaza el recuento de referencia.
El bloqueo se utiliza para mantener la coherencia de las estructuras de
datos, mientras que la referencia y contar es una técnica de gestión de
memoria. Por lo general, ambos son necesarios, y no deben confundirse entre
sí.

De hecho, muchas estructuras de datos pueden tener dos niveles de conteo de
referencias, cuando hay usuarios de diferentes ``clases``. El conteo de
subclases cuenta el número de usuarios de la subclase y disminuye el conteo
global solo una vez, cuando el recuento de subclases llega a cero.

Se pueden encontrar ejemplos de este tipo de ``recuento de referencias de
niveles múltiples`` en la gestión de memoria (``struct mm_struct``:
mm_users y mm_count), y en código del sistema de archivos
(``struct super_block``: s_count y s_active).

Recuerde: si otro hilo puede encontrar su estructura de datos y usted no
tiene un recuento de referencias, es casi seguro que tiene un error.

12) Macros, Enums y RTL
------------------------

Los nombres de macros que definen constantes y etiquetas en enumeraciones
(enums) están en mayúsculas.

.. code-block:: c

	#define CONSTANTE 0x12345

Se prefieren los enums cuando se definen varias constantes relacionadas.

Se aprecian los nombres de macro en MAYÚSCULAS, pero las macros que se
asemejan a funciones puede ser nombradas en minúscula.

Generalmente, las funciones en línea son preferibles a las macros que se
asemejan a funciones.

Las macros con varias instrucciones deben contenerse en un bloque do-while:

.. code-block:: c

	#define macrofun(a, b, c)			\
		do {					\
			if (a == 5)			\
				haz_esto(b, c);		\
		} while (0)

Cosas a evitar al usar macros:

1) macros que afectan el flujo de control:

.. code-block:: c

	#define FOO(x)					\
		do {					\
			if (blah(x) < 0)		\
				return -EBUGGERED;	\
		} while (0)

es una **muy** mala idea. Parece una llamada de función pero sale de la
función de ``llamada``; no rompa los analizadores internos de aquellos que
leerán el código.

2) macros que dependen de tener una variable local con un nombre mágico:

.. code-block:: c

	#define FOO(val) bar(index, val)

puede parecer algo bueno, pero es confuso como el infierno cuando uno lee
el código, y es propenso a romperse por cambios aparentemente inocentes.

3) macros con argumentos que se usan como valores l: FOO(x) = y; le van
a morder si alguien, por ejemplo, convierte FOO en una función en línea.

4) olvidarse de la precedencia: las macros que definen constantes usando
expresiones deben encerrar la expresión entre paréntesis. Tenga cuidado con
problemas similares con macros usando parámetros.

.. code-block:: c

	#define CONSTANTE 0x4000
	#define CONSTEXP (CONSTANTE | 3)

5) colisiones de espacio de nombres ("namespace") al definir variables
locales en macros que se asemejan a funciones:

.. code-block:: c

	#define FOO(x)				\
	({					\
		typeof(x) ret;			\
		ret = calc_ret(x);		\
		(ret);				\
	})

ret es un nombre común para una variable local -es menos probable que
__foo_ret colisione (coincida) con una variable existente.

El manual de cpp trata las macros de forma exhaustiva. El manual interno de
gcc también cubre RTL, que se usa frecuentemente con lenguaje ensamblador
en el kernel.

13) Imprimir mensajes del kernel
--------------------------------

A los desarrolladores del kernel les gusta ser vistos como alfabetizados.
Cuide la ortografía de los mensajes del kernel para causar una buena
impresión. No utilice contracciones incorrectas como ``dont``; use
``do not`` o ``don't`` en su lugar. Haga sus mensajes concisos, claros e
inequívocos.

Los mensajes del kernel no tienen que terminar con un punto.

Imprimir números entre paréntesis (%d) no agrega valor y debe evitarse.

Hay varias modelos de macros de diagnóstico de driver en <linux/dev_printk.h>
que debe usar para asegurarse de que los mensajes coincidan con el
dispositivo correcto y driver, y están etiquetados con el nivel correcto:
dev_err(), dev_warn(), dev_info(), y así sucesivamente. Para mensajes que
no están asociados con un dispositivo particular, <linux/printk.h> define
pr_notice(), pr_info(), pr_warn(), pr_err(), etc.

Crear buenos mensajes de depuración puede ser todo un desafío; y una vez
los tiene, pueden ser de gran ayuda para la resolución remota de problemas.
Sin embargo, la impresión de mensajes de depuración se maneja de manera
diferente a la impresión de otros mensajes que no son de depuración.
Mientras que las otras funciones pr_XXX() se imprimen incondicionalmente,
pr_debug() no lo hace; se compila fuera por defecto, a menos que DEBUG sea
definido o se establezca CONFIG_DYNAMIC_DEBUG. Eso es cierto para dev_dbg()
también, y una convención relacionada usa VERBOSE_DEBUG para agregar
mensajes dev_vdbg() a los ya habilitados por DEBUG.

Muchos subsistemas tienen opciones de depuración de Kconfig para activar
-DDEBUG en el Makefile correspondiente; en otros casos, los archivos
usan #define DEBUG. Y cuando un mensaje de depuración debe imprimirse
incondicionalmente, por ejemplo si es ya dentro de una sección #ifdef
relacionada con la depuración, printk(KERN_DEBUG ...) puede ser usado.

14) Reservando memoria
----------------------

El kernel proporciona los siguientes asignadores de memoria de propósito
general: kmalloc(), kzalloc(), kmalloc_array(), kcalloc(), vmalloc() y
vzalloc(). Consulte la documentación de la API para obtener más información.
a cerca de ellos. :ref:`Documentation/core-api/memory-allocation.rst
<memory_allocation>`

La forma preferida para pasar el tamaño de una estructura es la siguiente:

.. code-block:: c

	p = kmalloc(sizeof(*p), ...);

La forma alternativa donde se deletrea el nombre de la estructura perjudica
la legibilidad, y presenta una oportunidad para un error cuando se cambia
el tipo de variable de puntero, pero el tamaño correspondiente de eso que
se pasa a un asignador de memoria no.

Convertir el valor devuelto, que es un puntero vacío, es redundante. La
conversión desde el puntero vacío a cualquier otro tipo de puntero está
garantizado por la programación en idioma C.

La forma preferida para asignar una matriz es la siguiente:

.. code-block:: c

	p = kmalloc_array(n, sizeof(...), ...);

La forma preferida para asignar una matriz a cero es la siguiente:

.. code-block:: c

	p = kcalloc(n, sizeof(...), ...);

Ambos casos verifican el desbordamiento en el tamaño de asignación n *
sizeof (...), y devuelven NULL si esto ocurrió.

Todas estas funciones de asignación genéricas emiten un volcado de pila
(" stack dump") en caso de fallo cuando se usan sin __GFP_NOWARN, por lo
que no sirve de nada emitir un mensaje de fallo adicional cuando se
devuelva NULL.

15) La enfermedad de inline
----------------------------

Parece haber una común percepción errónea de que gcc tiene una magica
opción "hazme más rápido" de aceleración, llamada ``inline`` (en línea).
Mientras que el uso de inlines puede ser apropiado (por ejemplo, como un
medio para reemplazar macros, consulte el Capítulo 12), muy a menudo no lo
es. El uso abundante de la palabra clave inline conduce a una mayor kernel,
que a su vez ralentiza el sistema en su conjunto, debido a una mayor huella
de icache para la CPU, y sencillamente porque hay menos memoria disponible
para el pagecache. Solo piense en esto; un fallo en la memoria caché de la
página provoca una búsqueda de disco, que tarda fácilmente 5 milisegundos.
Hay MUCHOS ciclos de CPU que puede entrar en estos 5 milisegundos.

Una razonable regla general es no poner funciones inline que tengan más de
3 líneas de código en ellas. Una excepción a esta regla son los casos en
que se sabe que un parámetro es una constante en tiempo de compilación, y
como resultado de esto, usted *sabe*, el compilador podrá optimizar la
mayor parte de su función en tiempo de compilación. Para un buen ejemplo de
este último caso, véase la función en línea kmalloc().

A menudo, la gente argumenta que agregar funciones en línea que son
estáticas y se usan solo una vez, es siempre una victoria ya que no hay
perdida de espacio. Mientras esto es técnicamente correcto, gcc es capaz de
incorporarlos automáticamente sin ayuda, y esta el problema de
mantenimiento de eliminar el inline, cuando un segundo usuario supera el
valor potencial de la pista que le dice a gcc que haga algo que habría
hecho de todos modos.

16) Valores devueltos por función y sus nombres
-----------------------------------------------

Las funciones pueden devolver valores de muchos tipos diferentes, y uno de
lo más común es un valor que indica si la función tuvo éxito o ha fallado.
Dicho valor se puede representar como un número entero de código de error
(-Exxx = falla, 0 = éxito) o un booleano ``con éxito`` (0 = falla, distinto
de cero = éxito).

La mezcla de estos dos tipos de representaciones es una fuente fértil de
errores difíciles de encontrar. Si el lenguaje C incluyera una fuerte
distinción entre enteros y booleanos, el compilador encontraría estos
errores por nosotros... pero no lo hace. Para ayudar a prevenir tales
errores, siga siempre esta convención::

	Si el nombre de una función es una acción o un comando imperativo,
	la función debe devolver un número entero de código de error. si el nombre
	es un predicado, la función debe devolver un valor booleano "exitoso".

Por ejemplo, ``agregar trabajo`` es un comando, y la función
agregar_trabajo() devuelve 0 en caso de éxito o -EBUSY en caso de fracaso.
De la misma manera, ``dispositivo PCI presente`` es un predicado, y la
función pci_dev_present() devuelve 1 si tiene éxito en encontrar un
dispositivo coincidente o 0 si no es así.

Todas las funciones EXPORTed (exportadas) deben respetar esta convención,
al igual que todas las funciones publicas. Las funciones privadas
(estáticas) no lo necesitan, pero es recomendado que lo hagan.

Las funciones cuyo valor devuelto es el resultado real de un cálculo, en
lugar de una indicación de si el cómputo tuvo éxito, no están sujetas a
esta regla. Generalmente indican fallo al devolver valores fuera del rango
de resultados. Los ejemplos típicos serían funciones que devuelven
punteros; estos usan NULL o el mecanismo ERR_PTR para informar de fallos.

17) Usando bool
----------------

El tipo bool del kernel Linux es un alias para el tipo C99 _Bool. Los
valores booleanos pueden solo evaluar a 0 o 1, y la conversión implícita o
explícita a bool convierte automáticamente el valor en verdadero o falso.
Cuando se utilizan tipos booleanos,
!! no se necesita construcción, lo que elimina una clase de errores.

Cuando se trabaja con valores booleanos, se deben usar las definiciones
verdadera y falsa, en lugar de 1 y 0.

Los tipos de devolución de función bool y las variables de pila siempre
se pueden usar cuando esto sea adecuado. Se recomienda el uso de bool para
mejorar la legibilidad y, a menudo, es una mejor opción que 'int' para
almacenar valores booleanos.

No use bool si el diseño de la línea de caché o el tamaño del valor son
importantes, ya que su tamaño y la alineación varía según la arquitectura
compilada. Las estructuras que son optimizadas para la alineación y el
tamaño no debe usar bool.

Si una estructura tiene muchos valores verdadero/falso, considere
consolidarlos en un bitfield con miembros de 1 bit, o usando un tipo de
ancho fijo apropiado, como u8.

De manera similar, para los argumentos de función, se pueden consolidar
muchos valores verdaderos/falsos en un solo argumento bit a bit 'flags' y
'flags' a menudo, puede ser una alternativa de argumento más legible si los
sitios de llamada tienen constantes desnudas de tipo verdaderas/falsas.

De lo contrario, el uso limitado de bool en estructuras y argumentos puede
mejorar la legibilidad.

18) No reinvente las macros del kernel
---------------------------------------

El archivo de cabecera include/linux/kernel.h contiene una serie de macros
que debe usar, en lugar de programar explícitamente alguna variante de
estos por usted mismo. Por ejemplo, si necesita calcular la longitud de una
matriz, aproveche la macro

.. code-block:: c

	#define ARRAY_SIZE(x) (sizeof(x) / sizeof((x)[0]))

De manera similar, si necesita calcular el tamaño de algún miembro de la
estructura, use

.. code-block:: c

	#define sizeof_field(t, f) (sizeof(((t*)0)->f))

También hay macros min() y max() que realizan una verificación estricta de
tipos si lo necesita. Siéntase libre de leer detenidamente ese archivo de
encabezado para ver qué más ya está definido y que no debe reproducir en su
código.

19) Editores modeline y otros desastres
---------------------------------------

Algunos editores pueden interpretar la información de configuración
incrustada en los archivos fuente, indicado con marcadores especiales. Por
ejemplo, emacs interpreta las líneas marcadas como esto:

.. code-block:: c

	-*- mode: c -*-

O así:

.. code-block:: c

	/*
	Local Variables:
	compile-command: "gcc -DMAGIC_DEBUG_FLAG foo.c"
	End:
	*/

Vim interpreta los marcadores que se ven así:

.. code-block:: c

	/* vim:set sw=8 noet */

No incluya ninguno de estos en los archivos fuente. La gente tiene sus
propias configuraciones del editor, y sus archivos de origen no deben
anularlos. Esto incluye marcadores para sangría y configuración de modo.
La gente puede usar su propio modo personalizado, o puede tener algún otro
método mágico para que la sangría funcione correctamente.


20) Ensamblador inline
-----------------------

En el código específico de arquitectura, es posible que deba usar
ensamblador en línea para interactuar con funcionalidades de CPU o
plataforma. No dude en hacerlo cuando sea necesario. Sin embargo, no use
ensamblador en línea de forma gratuita cuando C puede hacer el trabajo.
Puede y debe empujar el hardware desde C cuando sea posible.

Considere escribir funciones auxiliares simples que envuelvan bits comunes
de ensamblador, en lugar de escribirlos repetidamente con ligeras
variaciones. Recuerde que el ensamblador en línea puede usar parámetros C.

Las funciones de ensamblador grandes y no triviales deben ir en archivos .S,
con su correspondientes prototipos de C definidos en archivos de encabezado
en C. Los prototipos de C para el ensamblador deben usar ``asmlinkage``.

Es posible que deba marcar su declaración asm como volátil, para evitar que
GCC la elimine si GCC no nota ningún efecto secundario. No siempre es
necesario hacerlo, sin embargo, y hacerlo innecesariamente puede limitar la
optimización.

Al escribir una sola declaración de ensamblador en línea que contiene
múltiples instrucciones, ponga cada instrucción en una línea separada en
una string separada, y termine cada string excepto la última con ``\n\t``
para indentar correctamente la siguiente instrucción en la salida en
ensamblador:

.. code-block:: c

	asm ("magic %reg1, #42\n\t"
	     "more_magic %reg2, %reg3"
	     : /* outputs */ : /* inputs */ : /* clobbers */);

21) Compilación condicional
---------------------------

Siempre que sea posible, no use condicionales de preprocesador (#if,
#ifdef) en archivos .c; de lo contrario, el código es más difícil de leer y
la lógica más difícil de seguir. En cambio, use dichos condicionales en un
archivo de encabezado que defina funciones para usar en esos archivos .c,
proporcionando versiones de código auxiliar sin operación en el caso #else,
y luego llame a estas funciones incondicionalmente desde archivos .c. El
compilador evitará generar cualquier código para las llamadas restantes,
produciendo resultados idénticos, pero la lógica es fácil de seguir.

Prefiera compilar funciones completas, en lugar de porciones de funciones o
porciones de expresiones. En lugar de poner un ifdef en una expresión,
divida la totalidad de la expresión con una función de ayuda independiente
y aplique el condicional a esa función.

Si tiene una función o variable que puede potencialmente quedar sin usar en
una configuración en particular, y el compilador advertiría sobre su
definición sin usar, marque la definición como __maybe_unused en lugar de
envolverla en un preprocesador condicional. (Sin embargo, si una función o
variable *siempre* acaba sin ser usada, bórrela.)

Dentro del código, cuando sea posible, use la macro IS_ENABLED para
convertir un símbolo Kconfig en una expresión booleana de C, y utilícelo en
un condicional de C normal:

.. code-block:: c

	if (IS_ENABLED(CONFIG_SOMETHING)) {
		...
	}

El compilador "doblará"" constantemente el condicional e incluirá o
excluirá el bloque de código al igual que con un #ifdef, por lo que esto no
agregará ningún tiempo de gastos generales en ejecución. Sin embargo, este
enfoque todavía permite que el compilador de C vea el código dentro del
bloque, y verifique que sea correcto (sintaxis, tipos, símbolo, referencias,
etc.). Por lo tanto, aún debe usar un #ifdef si el código dentro del bloque
hace referencia a símbolos que no existirán si no se cumple la condición.

Al final de cualquier bloque #if o #ifdef no trivial (más de unas pocas
líneas), incluya un comentario después de #endif en la misma línea,
anotando la expresión condicional utilizada. Por ejemplo:

.. code-block:: c

	#ifdef CONFIG_SOMETHING
	...
	#endif /* CONFIG_SOMETHING */

22) No rompa el kernel
-----------------------

En general, la decisión de romper el kernel pertenece al usuario, más que
al desarrollador del kernel.

Evite el panic()
****************

panic() debe usarse con cuidado y principalmente solo durante el arranque
del sistema. panic() es, por ejemplo, aceptable cuando se queda sin memoria
durante el arranque y no puede continuar.

Use WARN() en lugar de BUG()
****************************

No agregue código nuevo que use cualquiera de las variantes BUG(), como
BUG(), BUG_ON() o VM_BUG_ON(). En su lugar, use una variante WARN*(),
preferiblemente WARN_ON_ONCE(), y posiblemente con código de recuperación.
El código de recuperación no es requerido si no hay una forma razonable de
recuperar, al menos parcialmente.

"Soy demasiado perezoso para tener en cuenta los errores" no es una excusa
para usar BUG(). Importantes corrupciones internas sin forma de continuar
aún pueden usar BUG(), pero necesitan una buena justificación.

Use WARN_ON_ONCE() en lugar de WARN() o WARN_ON()
*************************************************

Generalmente, se prefiere WARN_ON_ONCE() a WARN() o WARN_ON(), porque es
común que una condición de advertencia dada, si ocurre, ocurra varias
veces. Esto puede llenar el registro del kernel, e incluso puede ralentizar
el sistema lo suficiente como para que el registro excesivo se convierta en
su propio, adicional problema.

No haga WARN a la ligera
************************

WARN*() está diseñado para situaciones inesperadas que nunca deberían
suceder. Las macros WARN*() no deben usarse para nada que se espera que
suceda durante un funcionamiento normal. No hay "checkeos" previos o
posteriores a la condición, por ejemplo. De nuevo: WARN*() no debe usarse
para una condición esperada que vaya a activarse fácilmente, por ejemplo,
mediante acciones en el espacio del usuario. pr_warn_once() es una
alternativa posible, si necesita notificar al usuario de un problema.

No se preocupe sobre panic_on_warn de usuarios
**********************************************

Algunas palabras más sobre panic_on_warn: Recuerde que ``panic_on_warn`` es
una opción disponible del kernel, y que muchos usuarios configuran esta
opción. Esta es la razón por la que hay un artículo de "No haga WARN a la
ligera", arriba. Sin embargo, la existencia de panic_on_warn de usuarios no
es una razón válida para evitar el uso juicioso de WARN*(). Esto se debe a
que quien habilita panic_on_warn, explícitamente pidió al kernel que
fallara si se dispara un WARN*(), y tales usuarios deben estar preparados
para afrontar las consecuencias de un sistema que es algo más probable que
se rompa.

Use BUILD_BUG_ON() para aserciones en tiempo de compilación
***********************************************************

El uso de BUILD_BUG_ON() es aceptable y recomendado, porque es una aserción
en tiempo de compilación, que no tiene efecto en tiempo de ejecución.

Apéndice I) Referencias
-----------------------

The C Programming Language, Segunda edicion
por Brian W. Kernighan and Dennis M. Ritchie.
Prentice Hall, Inc., 1988.
ISBN 0-13-110362-8 (paperback), 0-13-110370-9 (hardback).

The Practice of Programming
por Brian W. Kernighan and Rob Pike.
Addison-Wesley, Inc., 1999.
ISBN 0-201-61586-X.

manuales GCC - en cumplimiento con K&R y este texto - para cpp, gcc,
detalles de gcc y sangría, todo disponible en https://www.gnu.org/manual/

WG14 es el grupo de trabajo de estandarización internacional de la
programación en lenguaje C, URL: http://www.open-std.org/JTC1/SC22/WG14/

:ref:`process/coding-style.rst <codingstyle>` del kernel, por greg@kroah.com at OLS 2002:
http://www.kroah.com/linux/talks/ols_2002_kernel_codingstyle_talk/html/