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