1 .. include:: ../disclaimer-ita.rst
3 :Original: :ref:`Documentation/process/coding-style.rst <codingstyle>`
4 :Translator: Federico Vaga <federico.vaga@vaga.pv.it>
8 Stile del codice per il kernel Linux
9 ====================================
11 Questo è un breve documento che descrive lo stile di codice preferito per
12 il kernel Linux. Lo stile di codifica è molto personale e non voglio
13 **forzare** nessuno ad accettare il mio, ma questo stile è quello che
14 dev'essere usato per qualsiasi cosa che io sia in grado di mantenere, e l'ho
15 preferito anche per molte altre cose. Per favore, almeno tenete in
16 considerazione le osservazioni espresse qui.
18 La prima cosa che suggerisco è quella di stamparsi una copia degli standard
19 di codifica GNU e di NON leggerla. Bruciatela, è un grande gesto simbolico.
21 Comunque, ecco i punti:
26 La tabulazione (tab) è di 8 caratteri e così anche le indentazioni. Ci sono
27 alcuni movimenti di eretici che vorrebbero l'indentazione a 4 (o perfino 2!)
28 caratteri di profondità, che è simile al tentativo di definire il valore del
31 Motivazione: l'idea dell'indentazione è di definire chiaramente dove un blocco
32 di controllo inizia e finisce. Specialmente quando siete rimasti a guardare lo
33 schermo per 20 ore a file, troverete molto più facile capire i livelli di
34 indentazione se questi sono larghi.
36 Ora, alcuni rivendicano che un'indentazione da 8 caratteri sposta il codice
37 troppo a destra e che quindi rende difficile la lettura su schermi a 80
38 caratteri. La risposta a questa affermazione è che se vi servono più di 3
39 livelli di indentazione, siete comunque fregati e dovreste correggere il vostro
42 In breve, l'indentazione ad 8 caratteri rende più facile la lettura, e in
43 aggiunta vi avvisa quando state annidando troppo le vostre funzioni.
44 Tenete ben a mente questo avviso.
46 Al fine di facilitare l'indentazione del costrutto switch, si preferisce
47 allineare sulla stessa colonna la parola chiave ``switch`` e i suoi
48 subordinati ``case``. In questo modo si evita una doppia indentazione per
49 i ``case``. Un esempio.:
70 A meno che non vogliate nascondere qualcosa, non mettete più istruzioni sulla
75 if (condition) do_this;
76 do_something_everytime;
78 Non usate le virgole per evitare le parentesi:
85 Invece, usate sempre le parentesi per racchiudere più istruzioni.
94 Non mettete nemmeno più assegnamenti sulla stessa riga. Lo stile del kernel
95 è ultrasemplice. Evitate espressioni intricate.
98 Al di fuori dei commenti, della documentazione ed escludendo i Kconfig, gli
99 spazi non vengono mai usati per l'indentazione, e l'esempio qui sopra è
102 Procuratevi un buon editor di testo e non lasciate spazi bianchi alla fine
106 2) Spezzare righe lunghe e stringhe
107 -----------------------------------
109 Lo stile del codice riguarda la leggibilità e la manutenibilità utilizzando
112 Come limite di riga si preferiscono le 80 colonne.
114 Espressioni più lunghe di 80 colonne dovrebbero essere spezzettate in
115 pezzi più piccoli, a meno che eccedere le 80 colonne non aiuti ad
116 aumentare la leggibilità senza nascondere informazioni.
118 I nuovi pezzi derivati sono sostanzialmente più corti degli originali
119 e vengono posizionati più a destra. Uno stile molto comune è quello di
120 allineare i nuovi pezzi alla parentesi aperta di una funzione.
122 Lo stesso si applica, nei file d'intestazione, alle funzioni con una
123 lista di argomenti molto lunga.
125 Tuttavia, non spezzettate mai le stringhe visibili agli utenti come i
126 messaggi di printk, questo perché inibireste la possibilità
127 d'utilizzare grep per cercarle.
129 3) Posizionamento di parentesi graffe e spazi
130 ---------------------------------------------
132 Un altro problema che s'affronta sempre quando si parla di stile in C è
133 il posizionamento delle parentesi graffe. Al contrario della dimensione
134 dell'indentazione, non ci sono motivi tecnici sulla base dei quali scegliere
135 una strategia di posizionamento o un'altra; ma il modo qui preferito,
136 come mostratoci dai profeti Kernighan e Ritchie, è quello di
137 posizionare la parentesi graffa di apertura per ultima sulla riga, e quella
138 di chiusura per prima su una nuova riga, così:
146 Questo è valido per tutte le espressioni che non siano funzioni (if, switch,
147 for, while, do). Per esempio:
162 Tuttavia, c'è il caso speciale, le funzioni: queste hanno la parentesi graffa
163 di apertura all'inizio della riga successiva, quindi:
172 Eretici da tutto il mondo affermano che questa incoerenza è ...
173 insomma ... incoerente, ma tutte le persone ragionevoli sanno che (a)
174 K&R hanno **ragione** e (b) K&R hanno ragione. A parte questo, le funzioni
175 sono comunque speciali (non potete annidarle in C).
177 Notate che la graffa di chiusura è da sola su una riga propria, ad
178 **eccezione** di quei casi dove è seguita dalla continuazione della stessa
179 espressione, in pratica ``while`` nell'espressione do-while, oppure ``else``
180 nell'espressione if-else, come questo:
202 Inoltre, notate che questo posizionamento delle graffe minimizza il numero
203 di righe vuote senza perdere di leggibilità. In questo modo, dato che le
204 righe sul vostro schermo non sono una risorsa illimitata (pensate ad uno
205 terminale con 25 righe), avrete delle righe vuote da riempire con dei
208 Non usate inutilmente le graffe dove una singola espressione è sufficiente.
224 Questo non vale nel caso in cui solo un ramo dell'espressione if-else
225 contiene una sola espressione; in quest'ultimo caso usate le graffe per
237 Inoltre, usate le graffe se un ciclo contiene più di una semplice istruzione:
249 Lo stile del kernel Linux per quanto riguarda gli spazi, dipende
250 (principalmente) dalle funzioni e dalle parole chiave. Usate una spazio dopo
251 (quasi tutte) le parole chiave. L'eccezioni più evidenti sono sizeof, typeof,
252 alignof, e __attribute__, il cui aspetto è molto simile a quello delle
253 funzioni (e in Linux, solitamente, sono usate con le parentesi, anche se il
254 linguaggio non lo richiede; come ``sizeof info`` dopo aver dichiarato
255 ``struct fileinfo info``).
257 Quindi utilizzate uno spazio dopo le seguenti parole chiave::
259 if, switch, case, for, do, while
261 ma non con sizeof, typeof, alignof, o __attribute__. Ad esempio,
266 s = sizeof(struct file);
268 Non aggiungete spazi attorno (dentro) ad un'espressione fra parentesi. Questo
269 esempio è **brutto**:
274 s = sizeof( struct file );
276 Quando dichiarate un puntatore ad una variabile o una funzione che ritorna un
277 puntatore, il posto suggerito per l'asterisco ``*`` è adiacente al nome della
278 variabile o della funzione, e non adiacente al nome del tipo. Esempi:
284 unsigned long long memparse(char *ptr, char **retptr);
285 char *match_strdup(substring_t *s);
287 Usate uno spazio attorno (da ogni parte) alla maggior parte degli operatori
288 binari o ternari, come i seguenti::
290 = + - < > * / % | & ^ <= >= == != ? :
292 ma non mettete spazi dopo gli operatori unari::
294 & * + - ~ ! sizeof typeof alignof __attribute__ defined
296 nessuno spazio dopo l'operatore unario suffisso di incremento o decremento::
300 nessuno spazio dopo l'operatore unario prefisso di incremento o decremento::
304 e nessuno spazio attorno agli operatori dei membri di una struttura ``.`` e
307 Non lasciate spazi bianchi alla fine delle righe. Alcuni editor con
308 l'indentazione ``furba`` inseriranno gli spazi bianchi all'inizio di una nuova
309 riga in modo appropriato, quindi potrete scrivere la riga di codice successiva
310 immediatamente. Tuttavia, alcuni di questi stessi editor non rimuovono
311 questi spazi bianchi quando non scrivete nulla sulla nuova riga, ad esempio
312 perché volete lasciare una riga vuota. Il risultato è che finirete per avere
313 delle righe che contengono spazi bianchi in coda.
315 Git vi avviserà delle modifiche che aggiungono questi spazi vuoti di fine riga,
316 e può opzionalmente rimuoverli per conto vostro; tuttavia, se state applicando
317 una serie di modifiche, questo potrebbe far fallire delle modifiche successive
318 perché il contesto delle righe verrà cambiato.
323 C è un linguaggio spartano, e così dovrebbero esserlo i vostri nomi. Al
324 contrario dei programmatori Modula-2 o Pascal, i programmatori C non usano
325 nomi graziosi come ThisVariableIsATemporaryCounter. Un programmatore C
326 chiamerebbe questa variabile ``tmp``, che è molto più facile da scrivere e
327 non è una delle più difficili da capire.
329 TUTTAVIA, nonostante i nomi con notazione mista siano da condannare, i nomi
330 descrittivi per variabili globali sono un dovere. Chiamare una funzione
331 globale ``pippo`` è un insulto.
333 Le variabili GLOBALI (da usare solo se vi servono **davvero**) devono avere
334 dei nomi descrittivi, così come le funzioni globali. Se avete una funzione
335 che conta gli utenti attivi, dovreste chiamarla ``count_active_users()`` o
336 qualcosa di simile, **non** dovreste chiamarla ``cntusr()``.
338 Codificare il tipo di funzione nel suo nome (quella cosa chiamata notazione
339 ungherese) è stupido - il compilatore conosce comunque il tipo e
340 può verificarli, e inoltre confonde i programmatori.
342 Le variabili LOCALI dovrebbero avere nomi corti, e significativi. Se avete
343 un qualsiasi contatore di ciclo, probabilmente sarà chiamato ``i``.
344 Chiamarlo ``loop_counter`` non è produttivo, non ci sono possibilità che
345 ``i`` possa non essere capito. Analogamente, ``tmp`` può essere una qualsiasi
346 variabile che viene usata per salvare temporaneamente un valore.
348 Se avete paura di fare casino coi nomi delle vostre variabili locali, allora
349 avete un altro problema che è chiamato sindrome dello squilibrio dell'ormone
350 della crescita delle funzioni. Vedere il capitolo 6 (funzioni).
352 5) Definizione di tipi (typedef)
353 --------------------------------
355 Per favore non usate cose come ``vps_t``.
356 Usare il typedef per strutture e puntatori è uno **sbaglio**. Quando vedete:
362 nei sorgenti, cosa significa?
367 struct virtual_container *a;
369 potreste dire cos'è effettivamente ``a``.
371 Molte persone pensano che la definizione dei tipi ``migliori la leggibilità``.
372 Non molto. Sono utili per:
374 (a) gli oggetti completamente opachi (dove typedef viene proprio usato allo
375 scopo di **nascondere** cosa sia davvero l'oggetto).
377 Esempio: ``pte_t`` eccetera sono oggetti opachi che potete usare solamente
378 con le loro funzioni accessorie.
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.
385 (b) i tipi chiaramente interi, dove l'astrazione **aiuta** ad evitare
386 confusione sul fatto che siano ``int`` oppure ``long``.
388 u8/u16/u32 sono typedef perfettamente accettabili, anche se ricadono
389 nella categoria (d) piuttosto che in questa.
393 Ancora - dev'esserci una **ragione** per farlo. Se qualcosa è
394 ``unsigned long``, non c'è alcun bisogno di avere:
396 typedef unsigned long myfalgs_t;
398 ma se ci sono chiare circostanze in cui potrebbe essere ``unsigned int``
399 e in altre configurazioni ``unsigned long``, allora certamente typedef
402 (c) quando di rado create letteralmente dei **nuovi** tipi su cui effettuare
405 (d) circostanze eccezionali, in cui si definiscono nuovi tipi identici a
406 quelli definiti dallo standard C99.
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.
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.
415 (e) i tipi sicuri nella spazio utente.
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.
422 Magari ci sono altri casi validi, ma la regola di base dovrebbe essere di
423 non usare MAI MAI un typedef a meno che non rientri in una delle regole
426 In generale, un puntatore, o una struttura a cui si ha accesso diretto in
427 modo ragionevole, non dovrebbero **mai** essere definite con un typedef.
432 Le funzioni dovrebbero essere brevi e carine, e fare una cosa sola. Dovrebbero
433 occupare uno o due schermi di testo (come tutti sappiamo, la dimensione
434 di uno schermo secondo ISO/ANSI è di 80x24), e fare una cosa sola e bene.
436 La massima lunghezza di una funziona è inversamente proporzionale alla sua
437 complessità e al livello di indentazione di quella funzione. Quindi, se avete
438 una funzione che è concettualmente semplice ma che è implementata come un
439 lunga (ma semplice) sequenza di caso-istruzione, dove avete molte piccole cose
440 per molti casi differenti, allora va bene avere funzioni più lunghe.
442 Comunque, se avete una funzione complessa e sospettate che uno studente
443 non particolarmente dotato del primo anno delle scuole superiori potrebbe
444 non capire cosa faccia la funzione, allora dovreste attenervi strettamente ai
445 limiti. Usate funzioni di supporto con nomi descrittivi (potete chiedere al
446 compilatore di renderle inline se credete che sia necessario per le
447 prestazioni, e probabilmente farà un lavoro migliore di quanto avreste potuto
450 Un'altra misura delle funzioni sono il numero di variabili locali. Non
451 dovrebbero eccedere le 5-10, oppure state sbagliando qualcosa. Ripensate la
452 funzione, e dividetela in pezzettini. Generalmente, un cervello umano può
453 seguire facilmente circa 7 cose diverse, di più lo confonderebbe. Lo sai
454 d'essere brillante, ma magari vorresti riuscire a capire cos'avevi fatto due
457 Nei file sorgenti, separate le funzioni con una riga vuota. Se la funzione è
458 esportata, la macro **EXPORT** per questa funzione deve seguire immediatamente
459 la riga della parentesi graffa di chiusura. Ad esempio:
463 int system_is_up(void)
465 return system_state == SYSTEM_RUNNING;
467 EXPORT_SYMBOL(system_is_up);
469 Nei prototipi di funzione, includete i nomi dei parametri e i loro tipi.
470 Nonostante questo non sia richiesto dal linguaggio C, in Linux viene preferito
471 perché è un modo semplice per aggiungere informazioni importanti per il
474 Non usate la parola chiave ``extern`` coi prototipi di funzione perché
475 rende le righe più lunghe e non è strettamente necessario.
477 7) Centralizzare il ritorno delle funzioni
478 ------------------------------------------
480 Sebbene sia deprecata da molte persone, l'istruzione goto è impiegata di
481 frequente dai compilatori sotto forma di salto incondizionato.
483 L'istruzione goto diventa utile quando una funzione ha punti d'uscita multipli
484 e vanno eseguite alcune procedure di pulizia in comune. Se non è necessario
485 pulire alcunché, allora ritornate direttamente.
487 Assegnate un nome all'etichetta di modo che suggerisca cosa fa la goto o
488 perché esiste. Un esempio di un buon nome potrebbe essere ``out_free_buffer:``
489 se la goto libera (free) un ``buffer``. Evitate l'uso di nomi GW-BASIC come
490 ``err1:`` ed ``err2:``, potreste doverli riordinare se aggiungete o rimuovete
491 punti d'uscita, e inoltre rende difficile verificarne la correttezza.
493 I motivo per usare le goto sono:
495 - i salti incondizionati sono più facili da capire e seguire
496 - l'annidamento si riduce
497 - si evita di dimenticare, per errore, di aggiornare un singolo punto d'uscita
498 - aiuta il compilatore ad ottimizzare il codice ridondante ;)
507 buffer = kmalloc(SIZE, GFP_KERNEL);
516 goto out_free_buffer;
524 Un baco abbastanza comune di cui bisogna prendere nota è il ``one err bugs``
525 che assomiglia a questo:
534 Il baco in questo codice è che in alcuni punti d'uscita la variabile ``foo`` è
535 NULL. Normalmente si corregge questo baco dividendo la gestione dell'errore in
536 due parti ``err_free_bar:`` e ``err_free_foo:``:
546 Idealmente, dovreste simulare condizioni d'errore per verificare i vostri
553 I commenti sono una buona cosa, ma c'è anche il rischio di esagerare. MAI
554 spiegare COME funziona il vostro codice in un commento: è molto meglio
555 scrivere il codice di modo che il suo funzionamento sia ovvio, inoltre
556 spiegare codice scritto male è una perdita di tempo.
558 Solitamente, i commenti devono dire COSA fa il codice, e non COME lo fa.
559 Inoltre, cercate di evitare i commenti nel corpo della funzione: se la
560 funzione è così complessa che dovete commentarla a pezzi, allora dovreste
561 tornare al punto 6 per un momento. Potete mettere dei piccoli commenti per
562 annotare o avvisare il lettore circa un qualcosa di particolarmente arguto
563 (o brutto), ma cercate di non esagerare. Invece, mettete i commenti in
564 testa alla funzione spiegando alle persone cosa fa, e possibilmente anche
567 Per favore, quando commentate una funzione dell'API del kernel usate il
568 formato kernel-doc. Per maggiori dettagli, leggete i file in
569 :ref::ref:`Documentation/translations/it_IT/doc-guide/ <it_doc_guide>` e in
570 ``script/kernel-doc``.
572 Lo stile preferito per i commenti più lunghi (multi-riga) è:
577 * This is the preferred style for multi-line
578 * comments in the Linux kernel source code.
579 * Please use it consistently.
581 * Description: A column of asterisks on the left side,
582 * with beginning and ending almost-blank lines.
585 Per i file in net/ e in drivers/net/ lo stile preferito per i commenti
586 più lunghi (multi-riga) è leggermente diverso.
590 /* The preferred comment style for files in net/ and drivers/net
593 * It is nearly the same as the generally preferred comment style,
594 * but there is no initial almost-blank line.
597 È anche importante commentare i dati, sia per i tipi base che per tipi
598 derivati. A questo scopo, dichiarate un dato per riga (niente virgole
599 per una dichiarazione multipla). Questo vi lascerà spazio per un piccolo
600 commento per spiegarne l'uso.
603 9) Avete fatto un pasticcio
604 ---------------------------
606 Va bene, li facciamo tutti. Probabilmente vi è stato detto dal vostro
607 aiutante Unix di fiducia che ``GNU emacs`` formatta automaticamente il
608 codice C per conto vostro, e avete notato che sì, in effetti lo fa, ma che
609 i modi predefiniti non sono proprio allettanti (infatti, sono peggio che
610 premere tasti a caso - un numero infinito di scimmie che scrivono in
611 GNU emacs non faranno mai un buon programma).
613 Quindi, potete sbarazzarvi di GNU emacs, o riconfigurarlo con valori più
614 sensati. Per fare quest'ultima cosa, potete appiccicare il codice che
615 segue nel vostro file .emacs:
619 (defun c-lineup-arglist-tabs-only (ignored)
620 "Line up argument lists by tabs, not spaces"
621 (let* ((anchor (c-langelem-pos c-syntactic-element))
622 (column (c-langelem-2nd-pos c-syntactic-element))
623 (offset (- (1+ column) anchor))
624 (steps (floor offset c-basic-offset)))
628 (dir-locals-set-class-variables
632 (c-label-minimum-indentation . 0)
634 (arglist-close . c-lineup-arglist-tabs-only)
635 (arglist-cont-nonempty .
636 (c-lineup-gcc-asm-reg c-lineup-arglist-tabs-only))
638 (brace-list-intro . +)
639 (c . c-lineup-C-comments)
641 (comment-intro . c-lineup-comment)
642 (cpp-define-intro . +)
645 (defun-block-intro . +)
649 (inher-cont . c-lineup-multi-inher)
650 (knr-argdecl-intro . 0)
653 (statement-block-intro . +)
654 (statement-case-intro . +)
658 (indent-tabs-mode . t)
659 (show-trailing-whitespace . t)
662 (dir-locals-set-directory-class
663 (expand-file-name "~/src/linux-trees")
666 Questo farà funzionare meglio emacs con lo stile del kernel per i file che
667 si trovano nella cartella ``~/src/linux-trees``.
669 Ma anche se doveste fallire nell'ottenere una formattazione sensata in emacs
670 non tutto è perduto: usate ``indent``.
672 Ora, ancora, GNU indent ha la stessa configurazione decerebrata di GNU emacs,
673 ed è per questo che dovete passargli alcune opzioni da riga di comando.
674 Tuttavia, non è così terribile, perché perfino i creatori di GNU indent
675 riconoscono l'autorità di K&R (le persone del progetto GNU non sono cattive,
676 sono solo mal indirizzate sull'argomento), quindi date ad indent le opzioni
677 ``-kr -i8`` (che significa ``K&R, 8 caratteri di indentazione``), o utilizzate
678 ``scripts/Lindent`` che indenterà usando l'ultimo stile.
680 ``indent`` ha un sacco di opzioni, e specialmente quando si tratta di
681 riformattare i commenti dovreste dare un'occhiata alle pagine man.
682 Ma ricordatevi: ``indent`` non è un correttore per una cattiva programmazione.
684 Da notare che potete utilizzare anche ``clang-format`` per aiutarvi con queste
685 regole, per riformattare rapidamente ad automaticamente alcune parti del
686 vostro codice, e per revisionare interi file al fine di identificare errori
687 di stile, refusi e possibilmente anche delle migliorie. È anche utile per
688 ordinare gli ``#include``, per allineare variabili/macro, per ridistribuire
689 il testo e altre cose simili.
690 Per maggiori dettagli, consultate il file
691 :ref:`Documentation/translations/it_IT/process/clang-format.rst <it_clangformat>`.
694 10) File di configurazione Kconfig
695 ----------------------------------
697 Per tutti i file di configurazione Kconfig* che si possono trovare nei
698 sorgenti, l'indentazione è un po' differente. Le linee dopo un ``config``
699 sono indentate con un tab, mentre il testo descrittivo è indentato di
700 ulteriori due spazi. Esempio::
703 bool "Auditing support"
706 Enable auditing infrastructure that can be used with another
707 kernel subsystem, such as SELinux (which requires this for
708 logging of avc messages output). Does not do system-call
709 auditing without CONFIG_AUDITSYSCALL.
711 Le funzionalità davvero pericolose (per esempio il supporto alla scrittura
712 per certi filesystem) dovrebbero essere dichiarate chiaramente come tali
713 nella stringa di titolo::
716 bool "ADFS write support (DANGEROUS)"
720 Per la documentazione completa sui file di configurazione, consultate
721 il documento Documentation/kbuild/kconfig-language.rst
727 Le strutture dati che hanno una visibilità superiore al contesto del
728 singolo thread in cui vengono create e distrutte, dovrebbero sempre
729 avere un contatore di riferimenti. Nel kernel non esiste un
730 *garbage collector* (e fuori dal kernel i *garbage collector* sono lenti
731 e inefficienti), questo significa che **dovete** assolutamente avere un
732 contatore di riferimenti per ogni cosa che usate.
734 Avere un contatore di riferimenti significa che potete evitare la
735 sincronizzazione e permette a più utenti di accedere alla struttura dati
736 in parallelo - e non doversi preoccupare di una struttura dati che
737 improvvisamente sparisce dalla loro vista perché il loro processo dormiva
738 o stava facendo altro per un attimo.
740 Da notare che la sincronizzazione **non** si sostituisce al conteggio dei
741 riferimenti. La sincronizzazione ha lo scopo di mantenere le strutture
742 dati coerenti, mentre il conteggio dei riferimenti è una tecnica di gestione
743 della memoria. Solitamente servono entrambe le cose, e non vanno confuse fra
746 Quando si hanno diverse classi di utenti, le strutture dati possono avere
747 due livelli di contatori di riferimenti. Il contatore di classe conta
748 il numero dei suoi utenti, e il contatore globale viene decrementato una
749 sola volta quando il contatore di classe va a zero.
751 Un esempio di questo tipo di conteggio dei riferimenti multi-livello può
752 essere trovato nella gestore della memoria (``struct mm_sturct``: mm_user e
753 mm_count), e nel codice dei filesystem (``struct super_block``: s_count e
756 Ricordatevi: se un altro thread può trovare la vostra struttura dati, e non
757 avete un contatore di riferimenti per essa, quasi certamente avete un baco.
759 12) Macro, enumerati e RTL
760 ---------------------------
762 I nomi delle macro che definiscono delle costanti e le etichette degli
763 enumerati sono scritte in maiuscolo.
767 #define CONSTANT 0x12345
769 Gli enumerati sono da preferire quando si definiscono molte costanti correlate.
771 I nomi delle macro in MAIUSCOLO sono preferibili ma le macro che assomigliano
772 a delle funzioni possono essere scritte in minuscolo.
774 Generalmente, le funzioni inline sono preferibili rispetto alle macro che
777 Le macro che contengono più istruzioni dovrebbero essere sempre chiuse in un
782 #define macrofun(a, b, c) \
788 Cose da evitare quando si usano le macro:
790 1) le macro che hanno effetti sul flusso del codice:
800 sono **proprio** una pessima idea. Sembra una chiamata a funzione ma termina
801 la funzione chiamante; non cercate di rompere il decodificatore interno di
804 2) le macro che dipendono dall'uso di una variabile locale con un nome magico:
808 #define FOO(val) bar(index, val)
810 potrebbe sembrare una bella cosa, ma è dannatamente confusionario quando uno
811 legge il codice e potrebbe romperlo con una cambiamento che sembra innocente.
813 3) le macro con argomenti che sono utilizzati come l-values; questo potrebbe
814 ritorcervisi contro se qualcuno, per esempio, trasforma FOO in una funzione
817 4) dimenticatevi delle precedenze: le macro che definiscono espressioni devono
818 essere racchiuse fra parentesi. State attenti a problemi simili con le macro
823 #define CONSTANT 0x4000
824 #define CONSTEXP (CONSTANT | 3)
826 5) collisione nello spazio dei nomi quando si definisce una variabile locale in
827 una macro che sembra una funzione:
838 ret è un nome comune per una variabile locale - __foo_ret difficilmente
839 andrà in conflitto con una variabile già esistente.
841 Il manuale di cpp si occupa esaustivamente delle macro. Il manuale di sviluppo
842 di gcc copre anche l'RTL che viene usato frequentemente nel kernel per il
843 linguaggio assembler.
845 13) Visualizzare i messaggi del kernel
846 --------------------------------------
848 Agli sviluppatori del kernel piace essere visti come dotti. Tenete un occhio
849 di riguardo per l'ortografia e farete una belle figura. In inglese, evitate
850 l'uso incorretto di abbreviazioni come ``dont``: usate ``do not`` oppure
851 ``don't``. Scrivete messaggi concisi, chiari, e inequivocabili.
853 I messaggi del kernel non devono terminare con un punto fermo.
855 Scrivere i numeri fra parentesi (%d) non migliora alcunché e per questo
856 dovrebbero essere evitati.
858 Ci sono alcune macro per la diagnostica in <linux/device.h> che dovreste
859 usare per assicurarvi che i messaggi vengano associati correttamente ai
860 dispositivi e ai driver, e che siano etichettati correttamente: dev_err(),
861 dev_warn(), dev_info(), e così via. Per messaggi che non sono associati ad
862 alcun dispositivo, <linux/printk.h> definisce pr_info(), pr_warn(), pr_err(),
865 Tirar fuori un buon messaggio di debug può essere una vera sfida; e quando
866 l'avete può essere d'enorme aiuto per risolvere problemi da remoto.
867 Tuttavia, i messaggi di debug sono gestiti differentemente rispetto agli
868 altri. Le funzioni pr_XXX() stampano incondizionatamente ma pr_debug() no;
869 essa non viene compilata nella configurazione predefinita, a meno che
870 DEBUG o CONFIG_DYNAMIC_DEBUG non vengono impostati. Questo vale anche per
871 dev_dbg() e in aggiunta VERBOSE_DEBUG per aggiungere i messaggi dev_vdbg().
873 Molti sottosistemi hanno delle opzioni di debug in Kconfig che aggiungono
874 -DDEBUG nei corrispettivi Makefile, e in altri casi aggiungono #define DEBUG
875 in specifici file. Infine, quando un messaggio di debug dev'essere stampato
876 incondizionatamente, per esempio perché siete già in una sezione di debug
877 racchiusa in #ifdef, potete usare printk(KERN_DEBUG ...).
879 14) Assegnare memoria
880 ---------------------
882 Il kernel fornisce i seguenti assegnatori ad uso generico:
883 kmalloc(), kzalloc(), kmalloc_array(), kcalloc(), vmalloc(), e vzalloc().
884 Per maggiori informazioni, consultate la documentazione dell'API:
885 :ref:`Documentation/translations/it_IT/core-api/memory-allocation.rst <it_memory_allocation>`
887 Il modo preferito per passare la dimensione di una struttura è il seguente:
891 p = kmalloc(sizeof(*p), ...);
893 La forma alternativa, dove il nome della struttura viene scritto interamente,
894 peggiora la leggibilità e introduce possibili bachi quando il tipo di
895 puntatore cambia tipo ma il corrispondente sizeof non viene aggiornato.
897 Il valore di ritorno è un puntatore void, effettuare un cast su di esso è
898 ridondante. La conversione fra un puntatore void e un qualsiasi altro tipo
899 di puntatore è garantito dal linguaggio di programmazione C.
901 Il modo preferito per assegnare un vettore è il seguente:
905 p = kmalloc_array(n, sizeof(...), ...);
907 Il modo preferito per assegnare un vettore a zero è il seguente:
911 p = kcalloc(n, sizeof(...), ...);
913 Entrambe verificano la condizione di overflow per la dimensione
914 d'assegnamento n * sizeof(...), se accade ritorneranno NULL.
916 Questi allocatori generici producono uno *stack dump* in caso di fallimento
917 a meno che non venga esplicitamente specificato __GFP_NOWARN. Quindi, nella
918 maggior parte dei casi, è inutile stampare messaggi aggiuntivi quando uno di
919 questi allocatori ritornano un puntatore NULL.
924 Sembra che ci sia la percezione errata che gcc abbia una qualche magica
925 opzione "rendimi più veloce" chiamata ``inline``. In alcuni casi l'uso di
926 inline è appropriato (per esempio in sostituzione delle macro, vedi
927 capitolo 12), ma molto spesso non lo è. L'uso abbondante della parola chiave
928 inline porta ad avere un kernel più grande, che si traduce in un sistema nel
929 suo complesso più lento per via di una cache per le istruzioni della CPU più
930 grande e poi semplicemente perché ci sarà meno spazio disponibile per una
931 pagina di cache. Pensateci un attimo; una fallimento nella cache causa una
932 ricerca su disco che può tranquillamente richiedere 5 millisecondi. Ci sono
933 TANTI cicli di CPU che potrebbero essere usati in questi 5 millisecondi.
935 Spesso le persone dicono che aggiungere inline a delle funzioni dichiarate
936 static e utilizzare una sola volta è sempre una scelta vincente perché non
937 ci sono altri compromessi. Questo è tecnicamente vero ma gcc è in grado di
938 trasformare automaticamente queste funzioni in inline; i problemi di
939 manutenzione del codice per rimuovere gli inline quando compare un secondo
940 utente surclassano il potenziale vantaggio nel suggerire a gcc di fare una
941 cosa che avrebbe fatto comunque.
943 16) Nomi e valori di ritorno delle funzioni
944 -------------------------------------------
946 Le funzioni possono ritornare diversi tipi di valori, e uno dei più comuni
947 è quel valore che indica se una funzione ha completato con successo o meno.
948 Questo valore può essere rappresentato come un codice di errore intero
949 (-Exxx = fallimento, 0 = successo) oppure un booleano di successo
950 (0 = fallimento, non-zero = successo).
952 Mischiare questi due tipi di rappresentazioni è un terreno fertile per
953 i bachi più insidiosi. Se il linguaggio C includesse una forte distinzione
954 fra gli interi e i booleani, allora il compilatore potrebbe trovare questi
955 errori per conto nostro ... ma questo non c'è. Per evitare di imbattersi
956 in questo tipo di baco, seguite sempre la seguente convenzione::
958 Se il nome di una funzione è un'azione o un comando imperativo,
959 essa dovrebbe ritornare un codice di errore intero. Se il nome
960 è un predicato, la funzione dovrebbe ritornare un booleano di
963 Per esempio, ``add work`` è un comando, e la funzione add_work() ritorna 0
964 in caso di successo o -EBUSY in caso di fallimento. Allo stesso modo,
965 ``PCI device present`` è un predicato, e la funzione pci_dev_present() ritorna
966 1 se trova il dispositivo corrispondente con successo, altrimenti 0.
968 Tutte le funzioni esportate (EXPORT) devono rispettare questa convenzione, e
969 così dovrebbero anche tutte le funzioni pubbliche. Le funzioni private
970 (static) possono non seguire questa convenzione, ma è comunque raccomandato
973 Le funzioni il cui valore di ritorno è il risultato di una computazione,
974 piuttosto che l'indicazione sul successo di tale computazione, non sono
975 soggette a questa regola. Solitamente si indicano gli errori ritornando un
976 qualche valore fuori dai limiti. Un tipico esempio è quello delle funzioni
977 che ritornano un puntatore; queste utilizzano NULL o ERR_PTR come meccanismo
978 di notifica degli errori.
983 Nel kernel Linux il tipo bool deriva dal tipo _Bool dello standard C99.
984 Un valore bool può assumere solo i valori 0 o 1, e implicitamente o
985 esplicitamente la conversione a bool converte i valori in vero (*true*) o
986 falso (*false*). Quando si usa un tipo bool il costrutto !! non sarà più
987 necessario, e questo va ad eliminare una certa serie di bachi.
989 Quando si usano i valori booleani, dovreste utilizzare le definizioni di true
990 e false al posto dei valori 1 e 0.
992 Per il valore di ritorno delle funzioni e per le variabili sullo stack, l'uso
993 del tipo bool è sempre appropriato. L'uso di bool viene incoraggiato per
994 migliorare la leggibilità e spesso è molto meglio di 'int' nella gestione di
997 Non usate bool se per voi sono importanti l'ordine delle righe di cache o
998 la loro dimensione; la dimensione e l'allineamento cambia a seconda
999 dell'architettura per la quale è stato compilato. Le strutture che sono state
1000 ottimizzate per l'allineamento o la dimensione non dovrebbero usare bool.
1002 Se una struttura ha molti valori true/false, considerate l'idea di raggrupparli
1003 in un intero usando campi da 1 bit, oppure usate un tipo dalla larghezza fissa,
1006 Come per gli argomenti delle funzioni, molti valori true/false possono essere
1007 raggruppati in un singolo argomento a bit denominato 'flags'; spesso 'flags' è
1008 un'alternativa molto più leggibile se si hanno valori costanti per true/false.
1010 Detto ciò, un uso parsimonioso di bool nelle strutture dati e negli argomenti
1011 può migliorare la leggibilità.
1013 18) Non reinventate le macro del kernel
1014 ---------------------------------------
1016 Il file di intestazione include/linux/kernel.h contiene un certo numero
1017 di macro che dovreste usare piuttosto che implementarne una qualche variante.
1018 Per esempio, se dovete calcolare la lunghezza di un vettore, sfruttate la
1023 #define ARRAY_SIZE(x) (sizeof(x) / sizeof((x)[0]))
1025 Analogamente, se dovete calcolare la dimensione di un qualche campo di una
1030 #define sizeof_field(t, f) (sizeof(((t*)0)->f))
1032 Ci sono anche le macro min() e max() che, se vi serve, effettuano un controllo
1033 rigido sui tipi. Sentitevi liberi di leggere attentamente questo file
1034 d'intestazione per scoprire cos'altro è stato definito che non dovreste
1035 reinventare nel vostro codice.
1037 19) Linee di configurazione degli editor e altre schifezze
1038 -----------------------------------------------------------
1040 Alcuni editor possono interpretare dei parametri di configurazione integrati
1041 nei file sorgenti e indicati con dai marcatori speciali. Per esempio, emacs
1042 interpreta le linee marcate nel seguente modo:
1054 compile-command: "gcc -DMAGIC_DEBUG_FLAG foo.c"
1058 Vim interpreta i marcatori come questi:
1062 /* vim:set sw=8 noet */
1064 Non includete nessuna di queste cose nei file sorgenti. Le persone hanno le
1065 proprie configurazioni personali per l'editor, e i vostri sorgenti non
1066 dovrebbero sovrascrivergliele. Questo vale anche per i marcatori
1067 d'indentazione e di modalità d'uso. Le persone potrebbero aver configurato una
1068 modalità su misura, oppure potrebbero avere qualche altra magia per far
1069 funzionare bene l'indentazione.
1074 Nel codice specifico per un'architettura, potreste aver bisogno di codice
1075 *inline assembly* per interfacciarvi col processore o con una funzionalità
1076 specifica della piattaforma. Non esitate a farlo quando è necessario.
1077 Comunque, non usatele gratuitamente quando il C può fare la stessa cosa.
1078 Potete e dovreste punzecchiare l'hardware in C quando è possibile.
1080 Considerate la scrittura di una semplice funzione che racchiude pezzi comuni
1081 di codice assembler piuttosto che continuare a riscrivere delle piccole
1082 varianti. Ricordatevi che l' *inline assembly* può utilizzare i parametri C.
1084 Il codice assembler più corposo e non banale dovrebbe andare nei file .S,
1085 coi rispettivi prototipi C definiti nei file d'intestazione. I prototipi C
1086 per le funzioni assembler dovrebbero usare ``asmlinkage``.
1088 Potreste aver bisogno di marcare il vostro codice asm come volatile al fine
1089 d'evitare che GCC lo rimuova quando pensa che non ci siano effetti collaterali.
1090 Non c'è sempre bisogno di farlo, e farlo quando non serve limita le
1093 Quando scrivete una singola espressione *inline assembly* contenente più
1094 istruzioni, mettete ognuna di queste istruzioni in una stringa e riga diversa;
1095 ad eccezione dell'ultima stringa/istruzione, ognuna deve terminare con ``\n\t``
1096 al fine di allineare correttamente l'assembler che verrà generato:
1100 asm ("magic %reg1, #42\n\t"
1101 "more_magic %reg2, %reg3"
1102 : /* outputs */ : /* inputs */ : /* clobbers */);
1104 21) Compilazione sotto condizione
1105 ---------------------------------
1107 Ovunque sia possibile, non usate le direttive condizionali del preprocessore
1108 (#if, #ifdef) nei file .c; farlo rende il codice difficile da leggere e da
1109 seguire. Invece, usate queste direttive nei file d'intestazione per definire
1110 le funzioni usate nei file .c, fornendo i relativi stub nel caso #else,
1111 e quindi chiamate queste funzioni senza condizioni di preprocessore. Il
1112 compilatore non produrrà alcun codice per le funzioni stub, produrrà gli
1113 stessi risultati, e la logica rimarrà semplice da seguire.
1115 È preferibile non compilare intere funzioni piuttosto che porzioni d'esse o
1116 porzioni d'espressioni. Piuttosto che mettere una ifdef in un'espressione,
1117 fattorizzate parte dell'espressione, o interamente, in funzioni e applicate
1118 la direttiva condizionale su di esse.
1120 Se avete una variabile o funzione che potrebbe non essere usata in alcune
1121 configurazioni, e quindi il compilatore potrebbe avvisarvi circa la definizione
1122 inutilizzata, marcate questa definizione come __maybe_unused piuttosto che
1123 racchiuderla in una direttiva condizionale del preprocessore. (Comunque,
1124 se una variabile o funzione è *sempre* inutilizzata, rimuovetela).
1126 Nel codice, dov'è possibile, usate la macro IS_ENABLED per convertire i
1127 simboli Kconfig in espressioni booleane C, e quindi usatela nelle classiche
1132 if (IS_ENABLED(CONFIG_SOMETHING)) {
1136 Il compilatore valuterà la condizione come costante (constant-fold), e quindi
1137 includerà o escluderà il blocco di codice come se fosse in un #ifdef, quindi
1138 non ne aumenterà il tempo di esecuzione. Tuttavia, questo permette al
1139 compilatore C di vedere il codice nel blocco condizionale e verificarne la
1140 correttezza (sintassi, tipi, riferimenti ai simboli, eccetera). Quindi
1141 dovete comunque utilizzare #ifdef se il codice nel blocco condizionale esiste
1142 solo quando la condizione è soddisfatta.
1144 Alla fine di un blocco corposo di #if o #ifdef (più di alcune linee),
1145 mettete un commento sulla stessa riga di #endif, annotando la condizione
1146 che termina. Per esempio:
1150 #ifdef CONFIG_SOMETHING
1152 #endif /* CONFIG_SOMETHING */
1154 Appendice I) riferimenti
1155 ------------------------
1157 The C Programming Language, Second Edition
1158 by Brian W. Kernighan and Dennis M. Ritchie.
1159 Prentice Hall, Inc., 1988.
1160 ISBN 0-13-110362-8 (paperback), 0-13-110370-9 (hardback).
1162 The Practice of Programming
1163 by Brian W. Kernighan and Rob Pike.
1164 Addison-Wesley, Inc., 1999.
1167 Manuali GNU - nei casi in cui sono compatibili con K&R e questo documento -
1168 per indent, cpp, gcc e i suoi dettagli interni, tutto disponibile qui
1169 http://www.gnu.org/manual/
1171 WG14 è il gruppo internazionale di standardizzazione per il linguaggio C,
1172 URL: http://www.open-std.org/JTC1/SC22/WG14/
1174 Kernel process/coding-style.rst, by greg@kroah.com at OLS 2002:
1175 http://www.kroah.com/linux/talks/ols_2002_kernel_codingstyle_talk/html/