1 .. include:: ../disclaimer-ita.rst
2
3 :Original: :ref:`Documentation/process/coding-style.rst <codingstyle>`
4 :Translator: Federico Vaga <federico.vaga@vaga.pv.it>
5
6 .. _it_codingstyle:
7
8 Stile del codice per il kernel Linux
9 ====================================
10
11 Questo è un breve documento che descrive lo stile di codice preferito per
12 il kernel Linux. Lo stile di codifica è molto personale e non voglio
13 **forzare** nessuno ad accettare il mio, ma questo stile è quello che
14 dev'essere usato per qualsiasi cosa che io sia in grado di mantenere, e l'ho
15 preferito anche per molte altre cose. Per favore, almeno tenete in
16 considerazione le osservazioni espresse qui.
17
18 La prima cosa che suggerisco è quella di stamparsi una copia degli standard
19 di codifica GNU e di NON leggerla. Bruciatela, è un grande gesto simbolico.
20
21 Comunque, ecco i punti:
22
23 1) Indentazione
24 ---------------
25
26 La tabulazione (tab) è di 8 caratteri e così anche le indentazioni. Ci sono
27 alcuni movimenti di eretici che vorrebbero l'indentazione a 4 (o perfino 2!)
28 caratteri di profondità, che è simile al tentativo di definire il valore del
29 pi-greco a 3.
30
31 Motivazione: l'idea dell'indentazione è di definire chiaramente dove un blocco
32 di controllo inizia e finisce. Specialmente quando siete rimasti a guardare lo
33 schermo per 20 ore a file, troverete molto più facile capire i livelli di
34 indentazione se questi sono larghi.
35
36 Ora, alcuni rivendicano che un'indentazione da 8 caratteri sposta il codice
37 troppo a destra e che quindi rende difficile la lettura su schermi a 80
38 caratteri. La risposta a questa affermazione è che se vi servono più di 3
39 livelli di indentazione, siete comunque fregati e dovreste correggere il vostro
40 programma.
41
42 In breve, l'indentazione ad 8 caratteri rende più facile la lettura, e in
43 aggiunta vi avvisa quando state annidando troppo le vostre funzioni.
44 Tenete ben a mente questo avviso.
45
46 Al fine di facilitare l'indentazione del costrutto switch, si preferisce
47 allineare sulla stessa colonna la parola chiave ``switch`` e i suoi
48 subordinati ``case``. In questo modo si evita una doppia indentazione per
49 i ``case``. Un esempio.:
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 A meno che non vogliate nascondere qualcosa, non mettete più istruzioni sulla
71 stessa riga:
72
73 .. code-block:: c
74
75 if (condition) do_this;
76 do_something_everytime;
77
78 Non usate le virgole per evitare le parentesi:
79
80 .. code-block:: c
81
82 if (condition)
83 do_this(), do_that();
84
85 Invece, usate sempre le parentesi per racchiudere più istruzioni.
86
87 .. code-block:: c
88
89 if (condition) {
90 do_this();
91 do_that();
92 }
93
94 Non mettete nemmeno più assegnamenti sulla stessa riga. Lo stile del kernel
95 è ultrasemplice. Evitate espressioni intricate.
96
97
98 Al di fuori dei commenti, della documentazione ed escludendo i Kconfig, gli
99 spazi non vengono mai usati per l'indentazione, e l'esempio qui sopra è
100 volutamente errato.
101
102 Procuratevi un buon editor di testo e non lasciate spazi bianchi alla fine
103 delle righe.
104
105
106 2) Spezzare righe lunghe e stringhe
107 -----------------------------------
108
109 Lo stile del codice riguarda la leggibilità e la manutenibilità utilizzando
110 strumenti comuni.
111
112 Come limite di riga si preferiscono le 80 colonne.
113
114 Espressioni più lunghe di 80 colonne dovrebbero essere spezzettate in
115 pezzi più piccoli, a meno che eccedere le 80 colonne non aiuti ad
116 aumentare la leggibilità senza nascondere informazioni.
117
118 I nuovi pezzi derivati sono sostanzialmente più corti degli originali
119 e vengono posizionati più a destra. Uno stile molto comune è quello di
120 allineare i nuovi pezzi alla parentesi aperta di una funzione.
121
122 Lo stesso si applica, nei file d'intestazione, alle funzioni con una
123 lista di argomenti molto lunga.
124
125 Tuttavia, non spezzettate mai le stringhe visibili agli utenti come i
126 messaggi di printk, questo perché inibireste la possibilità
127 d'utilizzare grep per cercarle.
128
129 3) Posizionamento di parentesi graffe e spazi
130 ---------------------------------------------
131
132 Un altro problema che s'affronta sempre quando si parla di stile in C è
133 il posizionamento delle parentesi graffe. Al contrario della dimensione
134 dell'indentazione, non ci sono motivi tecnici sulla base dei quali scegliere
135 una strategia di posizionamento o un'altra; ma il modo qui preferito,
136 come mostratoci dai profeti Kernighan e Ritchie, è quello di
137 posizionare la parentesi graffa di apertura per ultima sulla riga, e quella
138 di chiusura per prima su una nuova riga, così:
139
140 .. code-block:: c
141
142 if (x is true) {
143 we do y
144 }
145
146 Questo è valido per tutte le espressioni che non siano funzioni (if, switch,
147 for, while, do). Per esempio:
148
149 .. code-block:: c
150
151 switch (action) {
152 case KOBJ_ADD:
153 return "add";
154 case KOBJ_REMOVE:
155 return "remove";
156 case KOBJ_CHANGE:
157 return "change";
158 default:
159 return NULL;
160 }
161
162 Tuttavia, c'è il caso speciale, le funzioni: queste hanno la parentesi graffa
163 di apertura all'inizio della riga successiva, quindi:
164
165 .. code-block:: c
166
167 int function(int x)
168 {
169 body of function
170 }
171
172 Eretici da tutto il mondo affermano che questa incoerenza è ...
173 insomma ... incoerente, ma tutte le persone ragionevoli sanno che (a)
174 K&R hanno **ragione** e (b) K&R hanno ragione. A parte questo, le funzioni
175 sono comunque speciali (non potete annidarle in C).
176
177 Notate che la graffa di chiusura è da sola su una riga propria, ad
178 **eccezione** di quei casi dove è seguita dalla continuazione della stessa
179 espressione, in pratica ``while`` nell'espressione do-while, oppure ``else``
180 nell'espressione if-else, come questo:
181
182 .. code-block:: c
183
184 do {
185 body of do-loop
186 } while (condition);
187
188 e
189
190 .. code-block:: c
191
192 if (x == y) {
193 ..
194 } else if (x > y) {
195 ...
196 } else {
197 ....
198 }
199
200 Motivazione: K&R.
201
202 Inoltre, notate che questo posizionamento delle graffe minimizza il numero
203 di righe vuote senza perdere di leggibilità. In questo modo, dato che le
204 righe sul vostro schermo non sono una risorsa illimitata (pensate ad uno
205 terminale con 25 righe), avrete delle righe vuote da riempire con dei
206 commenti.
207
208 Non usate inutilmente le graffe dove una singola espressione è sufficiente.
209
210 .. code-block:: c
211
212 if (condition)
213 action();
214
215 e
216
217 .. code-block:: c
218
219 if (condition)
220 do_this();
221 else
222 do_that();
223
224 Questo non vale nel caso in cui solo un ramo dell'espressione if-else
225 contiene una sola espressione; in quest'ultimo caso usate le graffe per
226 entrambe i rami:
227
228 .. code-block:: c
229
230 if (condition) {
231 do_this();
232 do_that();
233 } else {
234 otherwise();
235 }
236
237 Inoltre, usate le graffe se un ciclo contiene più di una semplice istruzione:
238
239 .. code-block:: c
240
241 while (condition) {
242 if (test)
243 do_something();
244 }
245
246 3.1) Spazi
247 **********
248
249 Lo stile del kernel Linux per quanto riguarda gli spazi, dipende
250 (principalmente) dalle funzioni e dalle parole chiave. Usate una spazio dopo
251 (quasi tutte) le parole chiave. L'eccezioni più evidenti sono sizeof, typeof,
252 alignof, e __attribute__, il cui aspetto è molto simile a quello delle
253 funzioni (e in Linux, solitamente, sono usate con le parentesi, anche se il
254 linguaggio non lo richiede; come ``sizeof info`` dopo aver dichiarato
255 ``struct fileinfo info``).
256
257 Quindi utilizzate uno spazio dopo le seguenti parole chiave::
258
259 if, switch, case, for, do, while
260
261 ma non con sizeof, typeof, alignof, o __attribute__. Ad esempio,
262
263 .. code-block:: c
264
265
266 s = sizeof(struct file);
267
268 Non aggiungete spazi attorno (dentro) ad un'espressione fra parentesi. Questo
269 esempio è **brutto**:
270
271 .. code-block:: c
272
273
274 s = sizeof( struct file );
275
276 Quando dichiarate un puntatore ad una variabile o una funzione che ritorna un
277 puntatore, il posto suggerito per l'asterisco ``*`` è adiacente al nome della
278 variabile o della funzione, e non adiacente al nome del tipo. Esempi:
279
280 .. code-block:: c
281
282
283 char *linux_banner;
284 unsigned long long memparse(char *ptr, char **retptr);
285 char *match_strdup(substring_t *s);
286
287 Usate uno spazio attorno (da ogni parte) alla maggior parte degli operatori
288 binari o ternari, come i seguenti::
289
290 = + - < > * / % | & ^ <= >= == != ? :
291
292 ma non mettete spazi dopo gli operatori unari::
293
294 & * + - ~ ! sizeof typeof alignof __attribute__ defined
295
296 nessuno spazio dopo l'operatore unario suffisso di incremento o decremento::
297
298 ++ --
299
300 nessuno spazio dopo l'operatore unario prefisso di incremento o decremento::
301
302 ++ --
303
304 e nessuno spazio attorno agli operatori dei membri di una struttura ``.`` e
305 ``->``.
306
307 Non lasciate spazi bianchi alla fine delle righe. Alcuni editor con
308 l'indentazione ``furba`` inseriranno gli spazi bianchi all'inizio di una nuova
309 riga in modo appropriato, quindi potrete scrivere la riga di codice successiva
310 immediatamente. Tuttavia, alcuni di questi stessi editor non rimuovono
311 questi spazi bianchi quando non scrivete nulla sulla nuova riga, ad esempio
312 perché volete lasciare una riga vuota. Il risultato è che finirete per avere
313 delle righe che contengono spazi bianchi in coda.
314
315 Git vi avviserà delle modifiche che aggiungono questi spazi vuoti di fine riga,
316 e può opzionalmente rimuoverli per conto vostro; tuttavia, se state applicando
317 una serie di modifiche, questo potrebbe far fallire delle modifiche successive
318 perché il contesto delle righe verrà cambiato.
319
320 4) Assegnare nomi
321 -----------------
322
323 C è un linguaggio spartano, e così dovrebbero esserlo i vostri nomi. Al
324 contrario dei programmatori Modula-2 o Pascal, i programmatori C non usano
325 nomi graziosi come ThisVariableIsATemporaryCounter. Un programmatore C
326 chiamerebbe questa variabile ``tmp``, che è molto più facile da scrivere e
327 non è una delle più difficili da capire.
328
329 TUTTAVIA, nonostante i nomi con notazione mista siano da condannare, i nomi
330 descrittivi per variabili globali sono un dovere. Chiamare una funzione
331 globale ``pippo`` è un insulto.
332
333 Le variabili GLOBALI (da usare solo se vi servono **davvero**) devono avere
334 dei nomi descrittivi, così come le funzioni globali. Se avete una funzione
335 che conta gli utenti attivi, dovreste chiamarla ``count_active_users()`` o
336 qualcosa di simile, **non** dovreste chiamarla ``cntusr()``.
337
338 Codificare il tipo di funzione nel suo nome (quella cosa chiamata notazione
339 ungherese) è stupido - il compilatore conosce comunque il tipo e
340 può verificarli, e inoltre confonde i programmatori.
341
342 Le variabili LOCALI dovrebbero avere nomi corti, e significativi. Se avete
343 un qualsiasi contatore di ciclo, probabilmente sarà chiamato ``i``.
344 Chiamarlo ``loop_counter`` non è produttivo, non ci sono possibilità che
345 ``i`` possa non essere capito. Analogamente, ``tmp`` può essere una qualsiasi
346 variabile che viene usata per salvare temporaneamente un valore.
347
348 Se avete paura di fare casino coi nomi delle vostre variabili locali, allora
349 avete un altro problema che è chiamato sindrome dello squilibrio dell'ormone
350 della crescita delle funzioni. Vedere il capitolo 6 (funzioni).
351
352 5) Definizione di tipi (typedef)
353 --------------------------------
354
355 Per favore non usate cose come ``vps_t``.
356 Usare il typedef per strutture e puntatori è uno **sbaglio**. Quando vedete:
357
358 .. code-block:: c
359
360 vps_t a;
361
362 nei sorgenti, cosa significa?
363 Se, invece, dicesse:
364
365 .. code-block:: c
366
367 struct virtual_container *a;
368
369 potreste dire cos'è effettivamente ``a``.
370
371 Molte persone pensano che la definizione dei tipi ``migliori la leggibilità``.
372 Non molto. Sono utili per:
373
374 (a) gli oggetti completamente opachi (dove typedef viene proprio usato allo
375 scopo di **nascondere** cosa sia davvero l'oggetto).
376
377 Esempio: ``pte_t`` eccetera sono oggetti opachi che potete usare solamente
378 con le loro funzioni accessorie.
379
380 .. note::
381 Gli oggetti opachi e le ``funzioni accessorie`` non sono, di per se,
382 una bella cosa. Il motivo per cui abbiamo cose come pte_t eccetera è
383 che davvero non c'è alcuna informazione portabile.
384
385 (b) i tipi chiaramente interi, dove l'astrazione **aiuta** ad evitare
386 confusione sul fatto che siano ``int`` oppure ``long``.
387
388 u8/u16/u32 sono typedef perfettamente accettabili, anche se ricadono
389 nella categoria (d) piuttosto che in questa.
390
391 .. note::
392
393 Ancora - dev'esserci una **ragione** per farlo. Se qualcosa è
394 ``unsigned long``, non c'è alcun bisogno di avere:
395
396 typedef unsigned long myfalgs_t;
397
398 ma se ci sono chiare circostanze in cui potrebbe essere ``unsigned int``
399 e in altre configurazioni ``unsigned long``, allora certamente typedef
400 è una buona scelta.
401
402 (c) quando di rado create letteralmente dei **nuovi** tipi su cui effettuare
403 verifiche.
404
405 (d) circostanze eccezionali, in cui si definiscono nuovi tipi identici a
406 quelli definiti dallo standard C99.
407
408 Nonostante ci voglia poco tempo per abituare occhi e cervello all'uso dei
409 tipi standard come ``uint32_t``, alcune persone ne obiettano l'uso.
410
411 Perciò, i tipi specifici di Linux ``u8/u16/u32/u64`` e i loro equivalenti
412 con segno, identici ai tipi standard, sono permessi- tuttavia, non sono
413 obbligatori per il nuovo codice.
414
415 (e) i tipi sicuri nella spazio utente.
416
417 In alcune strutture dati visibili dallo spazio utente non possiamo
418 richiedere l'uso dei tipi C99 e nemmeno i vari ``u32`` descritti prima.
419 Perciò, utilizziamo __u32 e tipi simili in tutte le strutture dati
420 condivise con lo spazio utente.
421
422 Magari ci sono altri casi validi, ma la regola di base dovrebbe essere di
423 non usare MAI MAI un typedef a meno che non rientri in una delle regole
424 descritte qui.
425
426 In generale, un puntatore, o una struttura a cui si ha accesso diretto in
427 modo ragionevole, non dovrebbero **mai** essere definite con un typedef.
428
429 6) Funzioni
430 -----------
431
432 Le funzioni dovrebbero essere brevi e carine, e fare una cosa sola. Dovrebbero
433 occupare uno o due schermi di testo (come tutti sappiamo, la dimensione
434 di uno schermo secondo ISO/ANSI è di 80x24), e fare una cosa sola e bene.
435
436 La massima lunghezza di una funziona è inversamente proporzionale alla sua
437 complessità e al livello di indentazione di quella funzione. Quindi, se avete
438 una funzione che è concettualmente semplice ma che è implementata come un
439 lunga (ma semplice) sequenza di caso-istruzione, dove avete molte piccole cose
440 per molti casi differenti, allora va bene avere funzioni più lunghe.
441
442 Comunque, se avete una funzione complessa e sospettate che uno studente
443 non particolarmente dotato del primo anno delle scuole superiori potrebbe
444 non capire cosa faccia la funzione, allora dovreste attenervi strettamente ai
445 limiti. Usate funzioni di supporto con nomi descrittivi (potete chiedere al
446 compilatore di renderle inline se credete che sia necessario per le
447 prestazioni, e probabilmente farà un lavoro migliore di quanto avreste potuto
448 fare voi).
449
450 Un'altra misura delle funzioni sono il numero di variabili locali. Non
451 dovrebbero eccedere le 5-10, oppure state sbagliando qualcosa. Ripensate la
452 funzione, e dividetela in pezzettini. Generalmente, un cervello umano può
453 seguire facilmente circa 7 cose diverse, di più lo confonderebbe. Lo sai
454 d'essere brillante, ma magari vorresti riuscire a capire cos'avevi fatto due
455 settimane prima.
456
457 Nei file sorgenti, separate le funzioni con una riga vuota. Se la funzione è
458 esportata, la macro **EXPORT** per questa funzione deve seguire immediatamente
459 la riga della parentesi graffa di chiusura. Ad esempio:
460
461 .. code-block:: c
462
463 int system_is_up(void)
464 {
465 return system_state == SYSTEM_RUNNING;
466 }
467 EXPORT_SYMBOL(system_is_up);
468
469 6.1) Prototipi di funzione
470 **************************
471
472 Nei prototipi di funzione, includete i nomi dei parametri e i loro tipi.
473 Nonostante questo non sia richiesto dal linguaggio C, in Linux viene preferito
474 perché è un modo semplice per aggiungere informazioni importanti per il
475 lettore.
476
477 Non usate la parola chiave ``extern`` con le dichiarazioni di funzione perché
478 rende le righe più lunghe e non è strettamente necessario.
479
480 Quando scrivete i prototipi di funzione mantenete `l'ordine degli elementi <https://lore.kernel.org/mm-commits/CAHk-=wiOCLRny5aifWNhr621kYrJwhfURsa0vFPeUEm8mF0ufg@mail.gmail.com/">https://lore.kernel.org/mm-commits/CAHk-=wiOCLRny5aifWNhr621kYrJwhfURsa0vFPeUEm8mF0ufg@mail.gmail.com/>`_.
481
482 Prendiamo questa dichiarazione di funzione come esempio::
483
484 __init void * __must_check action(enum magic value, size_t size, u8 count,
485 char *fmt, ...) __printf(4, 5) __malloc;
486
487 L'ordine suggerito per gli elementi di un prototipo di funzione è il seguente:
488
489 - classe d'archiviazione (in questo caso ``static __always_inline``. Da notare
490 che ``__always_inline`` è tecnicamente un attributo ma che viene trattato come
491 ``inline``)
492 - attributi della classe di archiviazione (in questo caso ``__init``, in altre
493 parole la sezione, ma anche cose tipo ``__cold``)
494 - il tipo di ritorno (in questo caso, ``void *``)
495 - attributi per il valore di ritorno (in questo caso, ``__must_check``)
496 - il nome della funzione (in questo caso, ``action``)
497 - i parametri della funzione(in questo caso,
498 ``(enum magic value, size_t size, u8 count, char *fmt, ...)``,
499 da notare che va messo anche il nome del parametro)
500 - attributi dei parametri (in questo caso, ``__printf(4, 5)``)
501 - attributi per il comportamento della funzione (in questo caso, ``__malloc_``)
502
503 Notate che per la **definizione** di una funzione (il altre parole il corpo
504 della funzione), il compilatore non permette di usare gli attributi per i
505 parametri dopo i parametri. In questi casi, devono essere messi dopo gli
506 attributi della classe d'archiviazione (notate che la posizione di
507 ``__printf(4,5)`` cambia rispetto alla **dichiarazione**)::
508
509 static __always_inline __init __printf(4, 5) void * __must_check action(enum magic value,
510 size_t size, u8 count, char *fmt, ...) __malloc
511 {
512 ...
513 }*)**``)**``)``)``*)``)``)``)``*``)``)``)*)
514
515 7) Centralizzare il ritorno delle funzioni
516 ------------------------------------------
517
518 Sebbene sia deprecata da molte persone, l'istruzione goto è impiegata di
519 frequente dai compilatori sotto forma di salto incondizionato.
520
521 L'istruzione goto diventa utile quando una funzione ha punti d'uscita multipli
522 e vanno eseguite alcune procedure di pulizia in comune. Se non è necessario
523 pulire alcunché, allora ritornate direttamente.
524
525 Assegnate un nome all'etichetta di modo che suggerisca cosa fa la goto o
526 perché esiste. Un esempio di un buon nome potrebbe essere ``out_free_buffer:``
527 se la goto libera (free) un ``buffer``. Evitate l'uso di nomi GW-BASIC come
528 ``err1:`` ed ``err2:``, potreste doverli riordinare se aggiungete o rimuovete
529 punti d'uscita, e inoltre rende difficile verificarne la correttezza.
530
531 I motivo per usare le goto sono:
532
533 - i salti incondizionati sono più facili da capire e seguire
534 - l'annidamento si riduce
535 - si evita di dimenticare, per errore, di aggiornare un singolo punto d'uscita
536 - aiuta il compilatore ad ottimizzare il codice ridondante ;)
537
538 .. code-block:: c
539
540 int fun(int a)
541 {
542 int result = 0;
543 char *buffer;
544
545 buffer = kmalloc(SIZE, GFP_KERNEL);
546 if (!buffer)
547 return -ENOMEM;
548
549 if (condition1) {
550 while (loop1) {
551 ...
552 }
553 result = 1;
554 goto out_free_buffer;
555 }
556 ...
557 out_free_buffer:
558 kfree(buffer);
559 return result;
560 }
561
562 Un baco abbastanza comune di cui bisogna prendere nota è il ``one err bugs``
563 che assomiglia a questo:
564
565 .. code-block:: c
566
567 err:
568 kfree(foo->bar);
569 kfree(foo);
570 return ret;
571
572 Il baco in questo codice è che in alcuni punti d'uscita la variabile ``foo`` è
573 NULL. Normalmente si corregge questo baco dividendo la gestione dell'errore in
574 due parti ``err_free_bar:`` e ``err_free_foo:``:
575
576 .. code-block:: c
577
578 err_free_bar:
579 kfree(foo->bar);
580 err_free_foo:
581 kfree(foo);
582 return ret;
583
584 Idealmente, dovreste simulare condizioni d'errore per verificare i vostri
585 percorsi d'uscita.
586
587
588 8) Commenti
589 -----------
590
591 I commenti sono una buona cosa, ma c'è anche il rischio di esagerare. MAI
592 spiegare COME funziona il vostro codice in un commento: è molto meglio
593 scrivere il codice di modo che il suo funzionamento sia ovvio, inoltre
594 spiegare codice scritto male è una perdita di tempo.
595
596 Solitamente, i commenti devono dire COSA fa il codice, e non COME lo fa.
597 Inoltre, cercate di evitare i commenti nel corpo della funzione: se la
598 funzione è così complessa che dovete commentarla a pezzi, allora dovreste
599 tornare al punto 6 per un momento. Potete mettere dei piccoli commenti per
600 annotare o avvisare il lettore circa un qualcosa di particolarmente arguto
601 (o brutto), ma cercate di non esagerare. Invece, mettete i commenti in
602 testa alla funzione spiegando alle persone cosa fa, e possibilmente anche
603 il PERCHÉ.
604
605 Per favore, quando commentate una funzione dell'API del kernel usate il
606 formato kernel-doc. Per maggiori dettagli, leggete i file in
607 :ref::ref:`Documentation/translations/it_IT/doc-guide/ <it_doc_guide>` e in
608 ``script/kernel-doc``.
609
610 Lo stile preferito per i commenti più lunghi (multi-riga) è:
611
612 .. code-block:: c
613
614 /*
615 * This is the preferred style for multi-line
616 * comments in the Linux kernel source code.
617 * Please use it consistently.
618 *
619 * Description: A column of asterisks on the left side,
620 * with beginning and ending almost-blank lines.
621 */
622
623 Per i file in net/ e in drivers/net/ lo stile preferito per i commenti
624 più lunghi (multi-riga) è leggermente diverso.
625
626 .. code-block:: c
627
628 /* The preferred comment style for files in net/ and drivers/net
629 * looks like this.
630 *
631 * It is nearly the same as the generally preferred comment style,
632 * but there is no initial almost-blank line.
633 */
634
635 È anche importante commentare i dati, sia per i tipi base che per tipi
636 derivati. A questo scopo, dichiarate un dato per riga (niente virgole
637 per una dichiarazione multipla). Questo vi lascerà spazio per un piccolo
638 commento per spiegarne l'uso.
639
640
641 9) Avete fatto un pasticcio
642 ---------------------------
643
644 Va bene, li facciamo tutti. Probabilmente vi è stato detto dal vostro
645 aiutante Unix di fiducia che ``GNU emacs`` formatta automaticamente il
646 codice C per conto vostro, e avete notato che sì, in effetti lo fa, ma che
647 i modi predefiniti non sono proprio allettanti (infatti, sono peggio che
648 premere tasti a caso - un numero infinito di scimmie che scrivono in
649 GNU emacs non faranno mai un buon programma).
650
651 Quindi, potete sbarazzarvi di GNU emacs, o riconfigurarlo con valori più
652 sensati. Per fare quest'ultima cosa, potete appiccicare il codice che
653 segue nel vostro file .emacs:
654
655 .. code-block:: elisp
656
657 (defun c-lineup-arglist-tabs-only (ignored)
658 "Line up argument lists by tabs, not spaces"
659 (let* ((anchor (c-langelem-pos c-syntactic-element))
660 (column (c-langelem-2nd-pos c-syntactic-element))
661 (offset (- (1+ column) anchor))
662 (steps (floor offset c-basic-offset)))
663 (* (max steps 1)
664 c-basic-offset)))
665
666 (dir-locals-set-class-variables
667 'linux-kernel
668 '((c-mode . (
669 (c-basic-offset . 8)
670 (c-label-minimum-indentation . 0)
671 (c-offsets-alist . (
672 (arglist-close . c-lineup-arglist-tabs-only)
673 (arglist-cont-nonempty .
674 (c-lineup-gcc-asm-reg c-lineup-arglist-tabs-only))
675 (arglist-intro . +)
676 (brace-list-intro . +)
677 (c . c-lineup-C-comments)
678 (case-label . 0)
679 (comment-intro . c-lineup-comment)
680 (cpp-define-intro . +)
681 (cpp-macro . -1000)
682 (cpp-macro-cont . +)
683 (defun-block-intro . +)
684 (else-clause . 0)
685 (func-decl-cont . +)
686 (inclass . +)
687 (inher-cont . c-lineup-multi-inher)
688 (knr-argdecl-intro . 0)
689 (label . -1000)
690 (statement . 0)
691 (statement-block-intro . +)
692 (statement-case-intro . +)
693 (statement-cont . +)
694 (substatement . +)
695 ))
696 (indent-tabs-mode . t)
697 (show-trailing-whitespace . t)
698 ))))
699
700 (dir-locals-set-directory-class
701 (expand-file-name "~/src/linux-trees")
702 'linux-kernel)
703
704 Questo farà funzionare meglio emacs con lo stile del kernel per i file che
705 si trovano nella cartella ``~/src/linux-trees``.
706
707 Ma anche se doveste fallire nell'ottenere una formattazione sensata in emacs
708 non tutto è perduto: usate ``indent``.
709
710 Ora, ancora, GNU indent ha la stessa configurazione decerebrata di GNU emacs,
711 ed è per questo che dovete passargli alcune opzioni da riga di comando.
712 Tuttavia, non è così terribile, perché perfino i creatori di GNU indent
713 riconoscono l'autorità di K&R (le persone del progetto GNU non sono cattive,
714 sono solo mal indirizzate sull'argomento), quindi date ad indent le opzioni
715 ``-kr -i8`` (che significa ``K&R, 8 caratteri di indentazione``), o utilizzate
716 ``scripts/Lindent`` che indenterà usando l'ultimo stile.
717
718 ``indent`` ha un sacco di opzioni, e specialmente quando si tratta di
719 riformattare i commenti dovreste dare un'occhiata alle pagine man.
720 Ma ricordatevi: ``indent`` non è un correttore per una cattiva programmazione.
721
722 Da notare che potete utilizzare anche ``clang-format`` per aiutarvi con queste
723 regole, per riformattare rapidamente ad automaticamente alcune parti del
724 vostro codice, e per revisionare interi file al fine di identificare errori
725 di stile, refusi e possibilmente anche delle migliorie. È anche utile per
726 ordinare gli ``#include``, per allineare variabili/macro, per ridistribuire
727 il testo e altre cose simili.
728 Per maggiori dettagli, consultate il file
729 :ref:`Documentation/translations/it_IT/process/clang-format.rst <it_clangformat>`.
730
731 Se utilizzate un programma compatibile con EditorConfig, allora alcune
732 configurazioni basilari come l'indentazione e la fine delle righe verranno
733 applicate automaticamente. Per maggiori informazioni consultate la pagina:
734 https://editorconfig.org/
735
736 10) File di configurazione Kconfig
737 ----------------------------------
738
739 Per tutti i file di configurazione Kconfig* che si possono trovare nei
740 sorgenti, l'indentazione è un po' differente. Le linee dopo un ``config``
741 sono indentate con un tab, mentre il testo descrittivo è indentato di
742 ulteriori due spazi. Esempio::
743
744 config AUDIT
745 bool "Auditing support"
746 depends on NET
747 help
748 Enable auditing infrastructure that can be used with another
749 kernel subsystem, such as SELinux (which requires this for
750 logging of avc messages output). Does not do system-call
751 auditing without CONFIG_AUDITSYSCALL.
752
753 Le funzionalità davvero pericolose (per esempio il supporto alla scrittura
754 per certi filesystem) dovrebbero essere dichiarate chiaramente come tali
755 nella stringa di titolo::
756
757 config ADFS_FS_RW
758 bool "ADFS write support (DANGEROUS)"
759 depends on ADFS_FS
760 ...
761
762 Per la documentazione completa sui file di configurazione, consultate
763 il documento Documentation/kbuild/kconfig-language.rst
764
765
766 11) Strutture dati
767 ------------------
768
769 Le strutture dati che hanno una visibilità superiore al contesto del
770 singolo thread in cui vengono create e distrutte, dovrebbero sempre
771 avere un contatore di riferimenti. Nel kernel non esiste un
772 *garbage collector* (e fuori dal kernel i *garbage collector* sono lenti
773 e inefficienti), questo significa che **dovete** assolutamente avere un
774 contatore di riferimenti per ogni cosa che usate.
775
776 Avere un contatore di riferimenti significa che potete evitare la
777 sincronizzazione e permette a più utenti di accedere alla struttura dati
778 in parallelo - e non doversi preoccupare di una struttura dati che
779 improvvisamente sparisce dalla loro vista perché il loro processo dormiva
780 o stava facendo altro per un attimo.
781
782 Da notare che la sincronizzazione **non** si sostituisce al conteggio dei
783 riferimenti. La sincronizzazione ha lo scopo di mantenere le strutture
784 dati coerenti, mentre il conteggio dei riferimenti è una tecnica di gestione
785 della memoria. Solitamente servono entrambe le cose, e non vanno confuse fra
786 di loro.
787
788 Quando si hanno diverse classi di utenti, le strutture dati possono avere
789 due livelli di contatori di riferimenti. Il contatore di classe conta
790 il numero dei suoi utenti, e il contatore globale viene decrementato una
791 sola volta quando il contatore di classe va a zero.
792
793 Un esempio di questo tipo di conteggio dei riferimenti multi-livello può
794 essere trovato nella gestore della memoria (``struct mm_sturct``: mm_user e
795 mm_count), e nel codice dei filesystem (``struct super_block``: s_count e
796 s_active).
797
798 Ricordatevi: se un altro thread può trovare la vostra struttura dati, e non
799 avete un contatore di riferimenti per essa, quasi certamente avete un baco.
800
801 12) Macro, enumerati e RTL
802 ---------------------------
803
804 I nomi delle macro che definiscono delle costanti e le etichette degli
805 enumerati sono scritte in maiuscolo.
806
807 .. code-block:: c
808
809 #define CONSTANT 0x12345
810
811 Gli enumerati sono da preferire quando si definiscono molte costanti correlate.
812
813 I nomi delle macro in MAIUSCOLO sono preferibili ma le macro che assomigliano
814 a delle funzioni possono essere scritte in minuscolo.
815
816 Generalmente, le funzioni inline sono preferibili rispetto alle macro che
817 sembrano funzioni.
818
819 Le macro che contengono più istruzioni dovrebbero essere sempre chiuse in un
820 blocco do - while:
821
822 .. code-block:: c
823
824 #define macrofun(a, b, c) \
825 do { \
826 if (a == 5) \
827 do_this(b, c); \
828 } while (0)
829
830 Cose da evitare quando si usano le macro:
831
832 1) le macro che hanno effetti sul flusso del codice:
833
834 .. code-block:: c
835
836 #define FOO(x) \
837 do { \
838 if (blah(x) < 0) \
839 return -EBUGGERED; \
840 } while (0)
841
842 sono **proprio** una pessima idea. Sembra una chiamata a funzione ma termina
843 la funzione chiamante; non cercate di rompere il decodificatore interno di
844 chi legge il codice.
845
846 2) le macro che dipendono dall'uso di una variabile locale con un nome magico:
847
848 .. code-block:: c
849
850 #define FOO(val) bar(index, val)
851
852 potrebbe sembrare una bella cosa, ma è dannatamente confusionario quando uno
853 legge il codice e potrebbe romperlo con una cambiamento che sembra innocente.
854
855 3) le macro con argomenti che sono utilizzati come l-values; questo potrebbe
856 ritorcervisi contro se qualcuno, per esempio, trasforma FOO in una funzione
857 inline.
858
859 4) dimenticatevi delle precedenze: le macro che definiscono espressioni devono
860 essere racchiuse fra parentesi. State attenti a problemi simili con le macro
861 parametrizzate.
862
863 .. code-block:: c
864
865 #define CONSTANT 0x4000
866 #define CONSTEXP (CONSTANT | 3)
867
868 5) collisione nello spazio dei nomi quando si definisce una variabile locale in
869 una macro che sembra una funzione:
870
871 .. code-block:: c
872
873 #define FOO(x) \
874 ({ \
875 typeof(x) ret; \
876 ret = calc_ret(x); \
877 (ret); \
878 })
879
880 ret è un nome comune per una variabile locale - __foo_ret difficilmente
881 andrà in conflitto con una variabile già esistente.
882
883 Il manuale di cpp si occupa esaustivamente delle macro. Il manuale di sviluppo
884 di gcc copre anche l'RTL che viene usato frequentemente nel kernel per il
885 linguaggio assembler.
886
887 13) Visualizzare i messaggi del kernel
888 --------------------------------------
889
890 Agli sviluppatori del kernel piace essere visti come dotti. Tenete un occhio
891 di riguardo per l'ortografia e farete una belle figura. In inglese, evitate
892 l'uso incorretto di abbreviazioni come ``dont``: usate ``do not`` oppure
893 ``don't``. Scrivete messaggi concisi, chiari, e inequivocabili.
894
895 I messaggi del kernel non devono terminare con un punto fermo.
896
897 Scrivere i numeri fra parentesi (%d) non migliora alcunché e per questo
898 dovrebbero essere evitati.
899
900 Ci sono alcune macro per la diagnostica in <linux/dev_printk.h> che dovreste
901 usare per assicurarvi che i messaggi vengano associati correttamente ai
902 dispositivi e ai driver, e che siano etichettati correttamente: dev_err(),
903 dev_warn(), dev_info(), e così via. Per messaggi che non sono associati ad
904 alcun dispositivo, <linux/printk.h> definisce pr_info(), pr_warn(), pr_err(),
905 eccetera. Quando tutto funziona correttamente, non dovrebbero esserci stampe,
906 per cui preferite dev_dbg/pr_debug a meno che non sia qualcosa di sbagliato
907 da segnalare.
908
909 Tirar fuori un buon messaggio di debug può essere una vera sfida; e quando
910 l'avete può essere d'enorme aiuto per risolvere problemi da remoto.
911 Tuttavia, i messaggi di debug sono gestiti differentemente rispetto agli
912 altri. Le funzioni pr_XXX() stampano incondizionatamente ma pr_debug() no;
913 essa non viene compilata nella configurazione predefinita, a meno che
914 DEBUG o CONFIG_DYNAMIC_DEBUG non vengono impostati. Questo vale anche per
915 dev_dbg() e in aggiunta VERBOSE_DEBUG per aggiungere i messaggi dev_vdbg().
916
917 Molti sottosistemi hanno delle opzioni di debug in Kconfig che aggiungono
918 -DDEBUG nei corrispettivi Makefile, e in altri casi aggiungono #define DEBUG
919 in specifici file. Infine, quando un messaggio di debug dev'essere stampato
920 incondizionatamente, per esempio perché siete già in una sezione di debug
921 racchiusa in #ifdef, potete usare printk(KERN_DEBUG ...).
922
923 14) Assegnare memoria
924 ---------------------
925
926 Il kernel fornisce i seguenti assegnatori ad uso generico:
927 kmalloc(), kzalloc(), kmalloc_array(), kcalloc(), vmalloc(), e vzalloc().
928 Per maggiori informazioni, consultate la documentazione dell'API:
929 :ref:`Documentation/translations/it_IT/core-api/memory-allocation.rst <it_memory_allocation>`
930
931 Il modo preferito per passare la dimensione di una struttura è il seguente:
932
933 .. code-block:: c
934
935 p = kmalloc(sizeof(*p), ...);
936
937 La forma alternativa, dove il nome della struttura viene scritto interamente,
938 peggiora la leggibilità e introduce possibili bachi quando il tipo di
939 puntatore cambia tipo ma il corrispondente sizeof non viene aggiornato.
940
941 Il valore di ritorno è un puntatore void, effettuare un cast su di esso è
942 ridondante. La conversione fra un puntatore void e un qualsiasi altro tipo
943 di puntatore è garantito dal linguaggio di programmazione C.
944
945 Il modo preferito per assegnare un vettore è il seguente:
946
947 .. code-block:: c
948
949 p = kmalloc_array(n, sizeof(...), ...);
950
951 Il modo preferito per assegnare un vettore a zero è il seguente:
952
953 .. code-block:: c
954
955 p = kcalloc(n, sizeof(...), ...);
956
957 Entrambe verificano la condizione di overflow per la dimensione
958 d'assegnamento n * sizeof(...), se accade ritorneranno NULL.
959
960 Questi allocatori generici producono uno *stack dump* in caso di fallimento
961 a meno che non venga esplicitamente specificato __GFP_NOWARN. Quindi, nella
962 maggior parte dei casi, è inutile stampare messaggi aggiuntivi quando uno di
963 questi allocatori ritornano un puntatore NULL.
964
965 15) Il morbo inline
966 -------------------
967
968 Sembra che ci sia la percezione errata che gcc abbia una qualche magica
969 opzione "rendimi più veloce" chiamata ``inline``. In alcuni casi l'uso di
970 inline è appropriato (per esempio in sostituzione delle macro, vedi
971 capitolo 12), ma molto spesso non lo è. L'uso abbondante della parola chiave
972 inline porta ad avere un kernel più grande, che si traduce in un sistema nel
973 suo complesso più lento per via di una cache per le istruzioni della CPU più
974 grande e poi semplicemente perché ci sarà meno spazio disponibile per una
975 pagina di cache. Pensateci un attimo; una fallimento nella cache causa una
976 ricerca su disco che può tranquillamente richiedere 5 millisecondi. Ci sono
977 TANTI cicli di CPU che potrebbero essere usati in questi 5 millisecondi.
978
979 Spesso le persone dicono che aggiungere inline a delle funzioni dichiarate
980 static e utilizzare una sola volta è sempre una scelta vincente perché non
981 ci sono altri compromessi. Questo è tecnicamente vero ma gcc è in grado di
982 trasformare automaticamente queste funzioni in inline; i problemi di
983 manutenzione del codice per rimuovere gli inline quando compare un secondo
984 utente surclassano il potenziale vantaggio nel suggerire a gcc di fare una
985 cosa che avrebbe fatto comunque.
986
987 16) Nomi e valori di ritorno delle funzioni
988 -------------------------------------------
989
990 Le funzioni possono ritornare diversi tipi di valori, e uno dei più comuni
991 è quel valore che indica se una funzione ha completato con successo o meno.
992 Questo valore può essere rappresentato come un codice di errore intero
993 (-Exxx = fallimento, 0 = successo) oppure un booleano di successo
994 (0 = fallimento, non-zero = successo).
995
996 Mischiare questi due tipi di rappresentazioni è un terreno fertile per
997 i bachi più insidiosi. Se il linguaggio C includesse una forte distinzione
998 fra gli interi e i booleani, allora il compilatore potrebbe trovare questi
999 errori per conto nostro ... ma questo non c'è. Per evitare di imbattersi
1000 in questo tipo di baco, seguite sempre la seguente convenzione::
1001
1002 Se il nome di una funzione è un'azione o un comando imperativo,
1003 essa dovrebbe ritornare un codice di errore intero. Se il nome
1004 è un predicato, la funzione dovrebbe ritornare un booleano di
1005 "successo"
1006
1007 Per esempio, ``add work`` è un comando, e la funzione add_work() ritorna 0
1008 in caso di successo o -EBUSY in caso di fallimento. Allo stesso modo,
1009 ``PCI device present`` è un predicato, e la funzione pci_dev_present() ritorna
1010 1 se trova il dispositivo corrispondente con successo, altrimenti 0.
1011
1012 Tutte le funzioni esportate (EXPORT) devono rispettare questa convenzione, e
1013 così dovrebbero anche tutte le funzioni pubbliche. Le funzioni private
1014 (static) possono non seguire questa convenzione, ma è comunque raccomandato
1015 che lo facciano.
1016
1017 Le funzioni il cui valore di ritorno è il risultato di una computazione,
1018 piuttosto che l'indicazione sul successo di tale computazione, non sono
1019 soggette a questa regola. Solitamente si indicano gli errori ritornando un
1020 qualche valore fuori dai limiti. Un tipico esempio è quello delle funzioni
1021 che ritornano un puntatore; queste utilizzano NULL o ERR_PTR come meccanismo
1022 di notifica degli errori.
1023
1024 17) L'uso di bool
1025 -----------------
1026
1027 Nel kernel Linux il tipo bool deriva dal tipo _Bool dello standard C99.
1028 Un valore bool può assumere solo i valori 0 o 1, e implicitamente o
1029 esplicitamente la conversione a bool converte i valori in vero (*true*) o
1030 falso (*false*). Quando si usa un tipo bool il costrutto !! non sarà più
1031 necessario, e questo va ad eliminare una certa serie di bachi.
1032
1033 Quando si usano i valori booleani, dovreste utilizzare le definizioni di true
1034 e false al posto dei valori 1 e 0.
1035
1036 Per il valore di ritorno delle funzioni e per le variabili sullo stack, l'uso
1037 del tipo bool è sempre appropriato. L'uso di bool viene incoraggiato per
1038 migliorare la leggibilità e spesso è molto meglio di 'int' nella gestione di
1039 valori booleani.
1040
1041 Non usate bool se per voi sono importanti l'ordine delle righe di cache o
1042 la loro dimensione; la dimensione e l'allineamento cambia a seconda
1043 dell'architettura per la quale è stato compilato. Le strutture che sono state
1044 ottimizzate per l'allineamento o la dimensione non dovrebbero usare bool.
1045
1046 Se una struttura ha molti valori true/false, considerate l'idea di raggrupparli
1047 in un intero usando campi da 1 bit, oppure usate un tipo dalla larghezza fissa,
1048 come u8.
1049
1050 Come per gli argomenti delle funzioni, molti valori true/false possono essere
1051 raggruppati in un singolo argomento a bit denominato 'flags'; spesso 'flags' è
1052 un'alternativa molto più leggibile se si hanno valori costanti per true/false.
1053
1054 Detto ciò, un uso parsimonioso di bool nelle strutture dati e negli argomenti
1055 può migliorare la leggibilità.
1056
1057 18) Non reinventate le macro del kernel
1058 ---------------------------------------
1059
1060 Il file di intestazione include/linux/kernel.h contiene un certo numero
1061 di macro che dovreste usare piuttosto che implementarne una qualche variante.
1062 Per esempio, se dovete calcolare la lunghezza di un vettore, sfruttate la
1063 macro:
1064
1065 .. code-block:: c
1066
1067 #define ARRAY_SIZE(x) (sizeof(x) / sizeof((x)[0]))
1068
1069 Analogamente, se dovete calcolare la dimensione di un qualche campo di una
1070 struttura, usate
1071
1072 .. code-block:: c
1073
1074 #define sizeof_field(t, f) (sizeof(((t*)0)->f))
1075
1076 Ci sono anche le macro min() e max() che, se vi serve, effettuano un controllo
1077 rigido sui tipi. Sentitevi liberi di leggere attentamente questo file
1078 d'intestazione per scoprire cos'altro è stato definito che non dovreste
1079 reinventare nel vostro codice.
1080
1081 19) Linee di configurazione degli editor e altre schifezze
1082 -----------------------------------------------------------
1083
1084 Alcuni editor possono interpretare dei parametri di configurazione integrati
1085 nei file sorgenti e indicati con dai marcatori speciali. Per esempio, emacs
1086 interpreta le linee marcate nel seguente modo:
1087
1088 .. code-block:: c
1089
1090 -*- mode: c -*-
1091
1092 O come queste:
1093
1094 .. code-block:: c
1095
1096 /*
1097 Local Variables:
1098 compile-command: "gcc -DMAGIC_DEBUG_FLAG foo.c"
1099 End:
1100 */
1101
1102 Vim interpreta i marcatori come questi:
1103
1104 .. code-block:: c
1105
1106 /* vim:set sw=8 noet */
1107
1108 Non includete nessuna di queste cose nei file sorgenti. Le persone hanno le
1109 proprie configurazioni personali per l'editor, e i vostri sorgenti non
1110 dovrebbero sovrascrivergliele. Questo vale anche per i marcatori
1111 d'indentazione e di modalità d'uso. Le persone potrebbero aver configurato una
1112 modalità su misura, oppure potrebbero avere qualche altra magia per far
1113 funzionare bene l'indentazione.
1114
1115 20) Inline assembly
1116 -------------------
1117
1118 Nel codice specifico per un'architettura, potreste aver bisogno di codice
1119 *inline assembly* per interfacciarvi col processore o con una funzionalità
1120 specifica della piattaforma. Non esitate a farlo quando è necessario.
1121 Comunque, non usatele gratuitamente quando il C può fare la stessa cosa.
1122 Potete e dovreste punzecchiare l'hardware in C quando è possibile.
1123
1124 Considerate la scrittura di una semplice funzione che racchiude pezzi comuni
1125 di codice assembler piuttosto che continuare a riscrivere delle piccole
1126 varianti. Ricordatevi che l' *inline assembly* può utilizzare i parametri C.
1127
1128 Il codice assembler più corposo e non banale dovrebbe andare nei file .S,
1129 coi rispettivi prototipi C definiti nei file d'intestazione. I prototipi C
1130 per le funzioni assembler dovrebbero usare ``asmlinkage``.
1131
1132 Potreste aver bisogno di marcare il vostro codice asm come volatile al fine
1133 d'evitare che GCC lo rimuova quando pensa che non ci siano effetti collaterali.
1134 Non c'è sempre bisogno di farlo, e farlo quando non serve limita le
1135 ottimizzazioni.
1136
1137 Quando scrivete una singola espressione *inline assembly* contenente più
1138 istruzioni, mettete ognuna di queste istruzioni in una stringa e riga diversa;
1139 ad eccezione dell'ultima stringa/istruzione, ognuna deve terminare con ``\n\t``
1140 al fine di allineare correttamente l'assembler che verrà generato:
1141
1142 .. code-block:: c
1143
1144 asm ("magic %reg1, #42\n\t"
1145 "more_magic %reg2, %reg3"
1146 : /* outputs */ : /* inputs */ : /* clobbers */);
1147
1148 21) Compilazione sotto condizione
1149 ---------------------------------
1150
1151 Ovunque sia possibile, non usate le direttive condizionali del preprocessore
1152 (#if, #ifdef) nei file .c; farlo rende il codice difficile da leggere e da
1153 seguire. Invece, usate queste direttive nei file d'intestazione per definire
1154 le funzioni usate nei file .c, fornendo i relativi stub nel caso #else,
1155 e quindi chiamate queste funzioni senza condizioni di preprocessore. Il
1156 compilatore non produrrà alcun codice per le funzioni stub, produrrà gli
1157 stessi risultati, e la logica rimarrà semplice da seguire.
1158
1159 È preferibile non compilare intere funzioni piuttosto che porzioni d'esse o
1160 porzioni d'espressioni. Piuttosto che mettere una ifdef in un'espressione,
1161 fattorizzate parte dell'espressione, o interamente, in funzioni e applicate
1162 la direttiva condizionale su di esse.
1163
1164 Se avete una variabile o funzione che potrebbe non essere usata in alcune
1165 configurazioni, e quindi il compilatore potrebbe avvisarvi circa la definizione
1166 inutilizzata, marcate questa definizione come __maybe_unused piuttosto che
1167 racchiuderla in una direttiva condizionale del preprocessore. (Comunque,
1168 se una variabile o funzione è *sempre* inutilizzata, rimuovetela).
1169
1170 Nel codice, dov'è possibile, usate la macro IS_ENABLED per convertire i
1171 simboli Kconfig in espressioni booleane C, e quindi usatela nelle classiche
1172 condizioni C:
1173
1174 .. code-block:: c
1175
1176 if (IS_ENABLED(CONFIG_SOMETHING)) {
1177 ...
1178 }
1179
1180 Il compilatore valuterà la condizione come costante (constant-fold), e quindi
1181 includerà o escluderà il blocco di codice come se fosse in un #ifdef, quindi
1182 non ne aumenterà il tempo di esecuzione. Tuttavia, questo permette al
1183 compilatore C di vedere il codice nel blocco condizionale e verificarne la
1184 correttezza (sintassi, tipi, riferimenti ai simboli, eccetera). Quindi
1185 dovete comunque utilizzare #ifdef se il codice nel blocco condizionale esiste
1186 solo quando la condizione è soddisfatta.
1187
1188 Alla fine di un blocco corposo di #if o #ifdef (più di alcune linee),
1189 mettete un commento sulla stessa riga di #endif, annotando la condizione
1190 che termina. Per esempio:
1191
1192 .. code-block:: c
1193
1194 #ifdef CONFIG_SOMETHING
1195 ...
1196 #endif /* CONFIG_SOMETHING */
1197
1198 Appendice I) riferimenti
1199 ------------------------
1200
1201 The C Programming Language, Second Edition
1202 by Brian W. Kernighan and Dennis M. Ritchie.
1203 Prentice Hall, Inc., 1988.
1204 ISBN 0-13-110362-8 (paperback), 0-13-110370-9 (hardback).
1205
1206 The Practice of Programming
1207 by Brian W. Kernighan and Rob Pike.
1208 Addison-Wesley, Inc., 1999.
1209 ISBN 0-201-61586-X.
1210
1211 Manuali GNU - nei casi in cui sono compatibili con K&R e questo documento -
1212 per indent, cpp, gcc e i suoi dettagli interni, tutto disponibile qui
1213 https://www.gnu.org/manual/
1214
1215 WG14 è il gruppo internazionale di standardizzazione per il linguaggio C,
1216 URL: https://www.open-std.org/JTC1/SC22/WG14/
1217
1218 Kernel CodingStyle, by greg@kroah.com at OLS 2002:
1219 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.