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