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 6.1) Prototipi di funzione
470 **************************
472 Nei prototipi di funzione, includete i nomi dei parametri e i loro tipi.
473 Nonostante questo non sia richiesto dal linguaggio C, in Linux viene preferito
474 perché è un modo semplice per aggiungere informazioni importanti per il
477 Non usate la parola chiave ``extern`` con le dichiarazioni di funzione perché
478 rende le righe più lunghe e non è strettamente necessario.
480 Quando scrivete i prototipi di funzione mantenete `l'ordine degli elementi <https://lore.kernel.org/mm-commits/CAHk-=wiOCLRny5aifWNhr621kYrJwhfURsa0vFPeUEm8mF0ufg@mail.gmail.com/>`_.
482 Prendiamo questa dichiarazione di funzione come esempio::
484 __init void * __must_check action(enum magic value, size_t size, u8 count,
485 char *fmt, ...) __printf(4, 5) __malloc;
487 L'ordine suggerito per gli elementi di un prototipo di funzione è il seguente:
489 - classe d'archiviazione (in questo caso ``static __always_inline``. Da notare
490 che ``__always_inline`` è tecnicamente un attributo ma che viene trattato come
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_``)
503 Notate che per la **definizione** di una funzione (il altre parole il corpo
504 della funzione), il compilatore non permette di usare gli attributi per i
505 parametri dopo i parametri. In questi casi, devono essere messi dopo gli
506 attributi della classe d'archiviazione (notate che la posizione di
507 ``__printf(4,5)`` cambia rispetto alla **dichiarazione**)::
509 static __always_inline __init __printf(4, 5) void * __must_check action(enum magic value,
510 size_t size, u8 count, char *fmt, ...) __malloc
513 }*)**``)**``)``)``*)``)``)``)``*``)``)``)*)
515 7) Centralizzare il ritorno delle funzioni
516 ------------------------------------------
518 Sebbene sia deprecata da molte persone, l'istruzione goto è impiegata di
519 frequente dai compilatori sotto forma di salto incondizionato.
521 L'istruzione goto diventa utile quando una funzione ha punti d'uscita multipli
522 e vanno eseguite alcune procedure di pulizia in comune. Se non è necessario
523 pulire alcunché, allora ritornate direttamente.
525 Assegnate un nome all'etichetta di modo che suggerisca cosa fa la goto o
526 perché esiste. Un esempio di un buon nome potrebbe essere ``out_free_buffer:``
527 se la goto libera (free) un ``buffer``. Evitate l'uso di nomi GW-BASIC come
528 ``err1:`` ed ``err2:``, potreste doverli riordinare se aggiungete o rimuovete
529 punti d'uscita, e inoltre rende difficile verificarne la correttezza.
531 I motivo per usare le goto sono:
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 ;)
545 buffer = kmalloc(SIZE, GFP_KERNEL);
554 goto out_free_buffer;
562 Un baco abbastanza comune di cui bisogna prendere nota è il ``one err bugs``
563 che assomiglia a questo:
572 Il baco in questo codice è che in alcuni punti d'uscita la variabile ``foo`` è
573 NULL. Normalmente si corregge questo baco dividendo la gestione dell'errore in
574 due parti ``err_free_bar:`` e ``err_free_foo:``:
584 Idealmente, dovreste simulare condizioni d'errore per verificare i vostri
591 I commenti sono una buona cosa, ma c'è anche il rischio di esagerare. MAI
592 spiegare COME funziona il vostro codice in un commento: è molto meglio
593 scrivere il codice di modo che il suo funzionamento sia ovvio, inoltre
594 spiegare codice scritto male è una perdita di tempo.
596 Solitamente, i commenti devono dire COSA fa il codice, e non COME lo fa.
597 Inoltre, cercate di evitare i commenti nel corpo della funzione: se la
598 funzione è così complessa che dovete commentarla a pezzi, allora dovreste
599 tornare al punto 6 per un momento. Potete mettere dei piccoli commenti per
600 annotare o avvisare il lettore circa un qualcosa di particolarmente arguto
601 (o brutto), ma cercate di non esagerare. Invece, mettete i commenti in
602 testa alla funzione spiegando alle persone cosa fa, e possibilmente anche
605 Per favore, quando commentate una funzione dell'API del kernel usate il
606 formato kernel-doc. Per maggiori dettagli, leggete i file in
607 :ref::ref:`Documentation/translations/it_IT/doc-guide/ <it_doc_guide>` e in
608 ``script/kernel-doc``.
610 Lo stile preferito per i commenti più lunghi (multi-riga) è:
615 * This is the preferred style for multi-line
616 * comments in the Linux kernel source code.
617 * Please use it consistently.
619 * Description: A column of asterisks on the left side,
620 * with beginning and ending almost-blank lines.
623 Per i file in net/ e in drivers/net/ lo stile preferito per i commenti
624 più lunghi (multi-riga) è leggermente diverso.
628 /* The preferred comment style for files in net/ and drivers/net
631 * It is nearly the same as the generally preferred comment style,
632 * but there is no initial almost-blank line.
635 È anche importante commentare i dati, sia per i tipi base che per tipi
636 derivati. A questo scopo, dichiarate un dato per riga (niente virgole
637 per una dichiarazione multipla). Questo vi lascerà spazio per un piccolo
638 commento per spiegarne l'uso.
641 9) Avete fatto un pasticcio
642 ---------------------------
644 Va bene, li facciamo tutti. Probabilmente vi è stato detto dal vostro
645 aiutante Unix di fiducia che ``GNU emacs`` formatta automaticamente il
646 codice C per conto vostro, e avete notato che sì, in effetti lo fa, ma che
647 i modi predefiniti non sono proprio allettanti (infatti, sono peggio che
648 premere tasti a caso - un numero infinito di scimmie che scrivono in
649 GNU emacs non faranno mai un buon programma).
651 Quindi, potete sbarazzarvi di GNU emacs, o riconfigurarlo con valori più
652 sensati. Per fare quest'ultima cosa, potete appiccicare il codice che
653 segue nel vostro file .emacs:
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)))
666 (dir-locals-set-class-variables
670 (c-label-minimum-indentation . 0)
672 (arglist-close . c-lineup-arglist-tabs-only)
673 (arglist-cont-nonempty .
674 (c-lineup-gcc-asm-reg c-lineup-arglist-tabs-only))
676 (brace-list-intro . +)
677 (c . c-lineup-C-comments)
679 (comment-intro . c-lineup-comment)
680 (cpp-define-intro . +)
683 (defun-block-intro . +)
687 (inher-cont . c-lineup-multi-inher)
688 (knr-argdecl-intro . 0)
691 (statement-block-intro . +)
692 (statement-case-intro . +)
696 (indent-tabs-mode . t)
697 (show-trailing-whitespace . t)
700 (dir-locals-set-directory-class
701 (expand-file-name "~/src/linux-trees")
704 Questo farà funzionare meglio emacs con lo stile del kernel per i file che
705 si trovano nella cartella ``~/src/linux-trees``.
707 Ma anche se doveste fallire nell'ottenere una formattazione sensata in emacs
708 non tutto è perduto: usate ``indent``.
710 Ora, ancora, GNU indent ha la stessa configurazione decerebrata di GNU emacs,
711 ed è per questo che dovete passargli alcune opzioni da riga di comando.
712 Tuttavia, non è così terribile, perché perfino i creatori di GNU indent
713 riconoscono l'autorità di K&R (le persone del progetto GNU non sono cattive,
714 sono solo mal indirizzate sull'argomento), quindi date ad indent le opzioni
715 ``-kr -i8`` (che significa ``K&R, 8 caratteri di indentazione``), o utilizzate
716 ``scripts/Lindent`` che indenterà usando l'ultimo stile.
718 ``indent`` ha un sacco di opzioni, e specialmente quando si tratta di
719 riformattare i commenti dovreste dare un'occhiata alle pagine man.
720 Ma ricordatevi: ``indent`` non è un correttore per una cattiva programmazione.
722 Da notare che potete utilizzare anche ``clang-format`` per aiutarvi con queste
723 regole, per riformattare rapidamente ad automaticamente alcune parti del
724 vostro codice, e per revisionare interi file al fine di identificare errori
725 di stile, refusi e possibilmente anche delle migliorie. È anche utile per
726 ordinare gli ``#include``, per allineare variabili/macro, per ridistribuire
727 il testo e altre cose simili.
728 Per maggiori dettagli, consultate il file
729 :ref:`Documentation/translations/it_IT/process/clang-format.rst <it_clangformat>`.
732 10) File di configurazione Kconfig
733 ----------------------------------
735 Per tutti i file di configurazione Kconfig* che si possono trovare nei
736 sorgenti, l'indentazione è un po' differente. Le linee dopo un ``config``
737 sono indentate con un tab, mentre il testo descrittivo è indentato di
738 ulteriori due spazi. Esempio::
741 bool "Auditing support"
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.
749 Le funzionalità davvero pericolose (per esempio il supporto alla scrittura
750 per certi filesystem) dovrebbero essere dichiarate chiaramente come tali
751 nella stringa di titolo::
754 bool "ADFS write support (DANGEROUS)"
758 Per la documentazione completa sui file di configurazione, consultate
759 il documento Documentation/kbuild/kconfig-language.rst
765 Le strutture dati che hanno una visibilità superiore al contesto del
766 singolo thread in cui vengono create e distrutte, dovrebbero sempre
767 avere un contatore di riferimenti. Nel kernel non esiste un
768 *garbage collector* (e fuori dal kernel i *garbage collector* sono lenti
769 e inefficienti), questo significa che **dovete** assolutamente avere un
770 contatore di riferimenti per ogni cosa che usate.
772 Avere un contatore di riferimenti significa che potete evitare la
773 sincronizzazione e permette a più utenti di accedere alla struttura dati
774 in parallelo - e non doversi preoccupare di una struttura dati che
775 improvvisamente sparisce dalla loro vista perché il loro processo dormiva
776 o stava facendo altro per un attimo.
778 Da notare che la sincronizzazione **non** si sostituisce al conteggio dei
779 riferimenti. La sincronizzazione ha lo scopo di mantenere le strutture
780 dati coerenti, mentre il conteggio dei riferimenti è una tecnica di gestione
781 della memoria. Solitamente servono entrambe le cose, e non vanno confuse fra
784 Quando si hanno diverse classi di utenti, le strutture dati possono avere
785 due livelli di contatori di riferimenti. Il contatore di classe conta
786 il numero dei suoi utenti, e il contatore globale viene decrementato una
787 sola volta quando il contatore di classe va a zero.
789 Un esempio di questo tipo di conteggio dei riferimenti multi-livello può
790 essere trovato nella gestore della memoria (``struct mm_sturct``: mm_user e
791 mm_count), e nel codice dei filesystem (``struct super_block``: s_count e
794 Ricordatevi: se un altro thread può trovare la vostra struttura dati, e non
795 avete un contatore di riferimenti per essa, quasi certamente avete un baco.
797 12) Macro, enumerati e RTL
798 ---------------------------
800 I nomi delle macro che definiscono delle costanti e le etichette degli
801 enumerati sono scritte in maiuscolo.
805 #define CONSTANT 0x12345
807 Gli enumerati sono da preferire quando si definiscono molte costanti correlate.
809 I nomi delle macro in MAIUSCOLO sono preferibili ma le macro che assomigliano
810 a delle funzioni possono essere scritte in minuscolo.
812 Generalmente, le funzioni inline sono preferibili rispetto alle macro che
815 Le macro che contengono più istruzioni dovrebbero essere sempre chiuse in un
820 #define macrofun(a, b, c) \
826 Cose da evitare quando si usano le macro:
828 1) le macro che hanno effetti sul flusso del codice:
838 sono **proprio** una pessima idea. Sembra una chiamata a funzione ma termina
839 la funzione chiamante; non cercate di rompere il decodificatore interno di
842 2) le macro che dipendono dall'uso di una variabile locale con un nome magico:
846 #define FOO(val) bar(index, val)
848 potrebbe sembrare una bella cosa, ma è dannatamente confusionario quando uno
849 legge il codice e potrebbe romperlo con una cambiamento che sembra innocente.
851 3) le macro con argomenti che sono utilizzati come l-values; questo potrebbe
852 ritorcervisi contro se qualcuno, per esempio, trasforma FOO in una funzione
855 4) dimenticatevi delle precedenze: le macro che definiscono espressioni devono
856 essere racchiuse fra parentesi. State attenti a problemi simili con le macro
861 #define CONSTANT 0x4000
862 #define CONSTEXP (CONSTANT | 3)
864 5) collisione nello spazio dei nomi quando si definisce una variabile locale in
865 una macro che sembra una funzione:
876 ret è un nome comune per una variabile locale - __foo_ret difficilmente
877 andrà in conflitto con una variabile già esistente.
879 Il manuale di cpp si occupa esaustivamente delle macro. Il manuale di sviluppo
880 di gcc copre anche l'RTL che viene usato frequentemente nel kernel per il
881 linguaggio assembler.
883 13) Visualizzare i messaggi del kernel
884 --------------------------------------
886 Agli sviluppatori del kernel piace essere visti come dotti. Tenete un occhio
887 di riguardo per l'ortografia e farete una belle figura. In inglese, evitate
888 l'uso incorretto di abbreviazioni come ``dont``: usate ``do not`` oppure
889 ``don't``. Scrivete messaggi concisi, chiari, e inequivocabili.
891 I messaggi del kernel non devono terminare con un punto fermo.
893 Scrivere i numeri fra parentesi (%d) non migliora alcunché e per questo
894 dovrebbero essere evitati.
896 Ci sono alcune macro per la diagnostica in <linux/dev_printk.h> che dovreste
897 usare per assicurarvi che i messaggi vengano associati correttamente ai
898 dispositivi e ai driver, e che siano etichettati correttamente: dev_err(),
899 dev_warn(), dev_info(), e così via. Per messaggi che non sono associati ad
900 alcun dispositivo, <linux/printk.h> definisce pr_info(), pr_warn(), pr_err(),
903 Tirar fuori un buon messaggio di debug può essere una vera sfida; e quando
904 l'avete può essere d'enorme aiuto per risolvere problemi da remoto.
905 Tuttavia, i messaggi di debug sono gestiti differentemente rispetto agli
906 altri. Le funzioni pr_XXX() stampano incondizionatamente ma pr_debug() no;
907 essa non viene compilata nella configurazione predefinita, a meno che
908 DEBUG o CONFIG_DYNAMIC_DEBUG non vengono impostati. Questo vale anche per
909 dev_dbg() e in aggiunta VERBOSE_DEBUG per aggiungere i messaggi dev_vdbg().
911 Molti sottosistemi hanno delle opzioni di debug in Kconfig che aggiungono
912 -DDEBUG nei corrispettivi Makefile, e in altri casi aggiungono #define DEBUG
913 in specifici file. Infine, quando un messaggio di debug dev'essere stampato
914 incondizionatamente, per esempio perché siete già in una sezione di debug
915 racchiusa in #ifdef, potete usare printk(KERN_DEBUG ...).
917 14) Assegnare memoria
918 ---------------------
920 Il kernel fornisce i seguenti assegnatori ad uso generico:
921 kmalloc(), kzalloc(), kmalloc_array(), kcalloc(), vmalloc(), e vzalloc().
922 Per maggiori informazioni, consultate la documentazione dell'API:
923 :ref:`Documentation/translations/it_IT/core-api/memory-allocation.rst <it_memory_allocation>`
925 Il modo preferito per passare la dimensione di una struttura è il seguente:
929 p = kmalloc(sizeof(*p), ...);
931 La forma alternativa, dove il nome della struttura viene scritto interamente,
932 peggiora la leggibilità e introduce possibili bachi quando il tipo di
933 puntatore cambia tipo ma il corrispondente sizeof non viene aggiornato.
935 Il valore di ritorno è un puntatore void, effettuare un cast su di esso è
936 ridondante. La conversione fra un puntatore void e un qualsiasi altro tipo
937 di puntatore è garantito dal linguaggio di programmazione C.
939 Il modo preferito per assegnare un vettore è il seguente:
943 p = kmalloc_array(n, sizeof(...), ...);
945 Il modo preferito per assegnare un vettore a zero è il seguente:
949 p = kcalloc(n, sizeof(...), ...);
951 Entrambe verificano la condizione di overflow per la dimensione
952 d'assegnamento n * sizeof(...), se accade ritorneranno NULL.
954 Questi allocatori generici producono uno *stack dump* in caso di fallimento
955 a meno che non venga esplicitamente specificato __GFP_NOWARN. Quindi, nella
956 maggior parte dei casi, è inutile stampare messaggi aggiuntivi quando uno di
957 questi allocatori ritornano un puntatore NULL.
962 Sembra che ci sia la percezione errata che gcc abbia una qualche magica
963 opzione "rendimi più veloce" chiamata ``inline``. In alcuni casi l'uso di
964 inline è appropriato (per esempio in sostituzione delle macro, vedi
965 capitolo 12), ma molto spesso non lo è. L'uso abbondante della parola chiave
966 inline porta ad avere un kernel più grande, che si traduce in un sistema nel
967 suo complesso più lento per via di una cache per le istruzioni della CPU più
968 grande e poi semplicemente perché ci sarà meno spazio disponibile per una
969 pagina di cache. Pensateci un attimo; una fallimento nella cache causa una
970 ricerca su disco che può tranquillamente richiedere 5 millisecondi. Ci sono
971 TANTI cicli di CPU che potrebbero essere usati in questi 5 millisecondi.
973 Spesso le persone dicono che aggiungere inline a delle funzioni dichiarate
974 static e utilizzare una sola volta è sempre una scelta vincente perché non
975 ci sono altri compromessi. Questo è tecnicamente vero ma gcc è in grado di
976 trasformare automaticamente queste funzioni in inline; i problemi di
977 manutenzione del codice per rimuovere gli inline quando compare un secondo
978 utente surclassano il potenziale vantaggio nel suggerire a gcc di fare una
979 cosa che avrebbe fatto comunque.
981 16) Nomi e valori di ritorno delle funzioni
982 -------------------------------------------
984 Le 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.
986 Questo 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).
990 Mischiare questi due tipi di rappresentazioni è un terreno fertile per
991 i bachi più insidiosi. Se il linguaggio C includesse una forte distinzione
992 fra gli interi e i booleani, allora il compilatore potrebbe trovare questi
993 errori per conto nostro ... ma questo non c'è. Per evitare di imbattersi
994 in questo tipo di baco, seguite sempre la seguente convenzione::
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
1001 Per esempio, ``add work`` è un comando, e la funzione add_work() ritorna 0
1002 in 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
1004 1 se trova il dispositivo corrispondente con successo, altrimenti 0.
1006 Tutte le funzioni esportate (EXPORT) devono rispettare questa convenzione, e
1007 così dovrebbero anche tutte le funzioni pubbliche. Le funzioni private
1008 (static) possono non seguire questa convenzione, ma è comunque raccomandato
1011 Le funzioni il cui valore di ritorno è il risultato di una computazione,
1012 piuttosto che l'indicazione sul successo di tale computazione, non sono
1013 soggette a questa regola. Solitamente si indicano gli errori ritornando un
1014 qualche valore fuori dai limiti. Un tipico esempio è quello delle funzioni
1015 che ritornano un puntatore; queste utilizzano NULL o ERR_PTR come meccanismo
1016 di notifica degli errori.
1021 Nel kernel Linux il tipo bool deriva dal tipo _Bool dello standard C99.
1022 Un valore bool può assumere solo i valori 0 o 1, e implicitamente o
1023 esplicitamente la conversione a bool converte i valori in vero (*true*) o
1024 falso (*false*). Quando si usa un tipo bool il costrutto !! non sarà più
1025 necessario, e questo va ad eliminare una certa serie di bachi.
1027 Quando si usano i valori booleani, dovreste utilizzare le definizioni di true
1028 e false al posto dei valori 1 e 0.
1030 Per il valore di ritorno delle funzioni e per le variabili sullo stack, l'uso
1031 del tipo bool è sempre appropriato. L'uso di bool viene incoraggiato per
1032 migliorare la leggibilità e spesso è molto meglio di 'int' nella gestione di
1035 Non usate bool se per voi sono importanti l'ordine delle righe di cache o
1036 la loro dimensione; la dimensione e l'allineamento cambia a seconda
1037 dell'architettura per la quale è stato compilato. Le strutture che sono state
1038 ottimizzate per l'allineamento o la dimensione non dovrebbero usare bool.
1040 Se una struttura ha molti valori true/false, considerate l'idea di raggrupparli
1041 in un intero usando campi da 1 bit, oppure usate un tipo dalla larghezza fissa,
1044 Come per gli argomenti delle funzioni, molti valori true/false possono essere
1045 raggruppati in un singolo argomento a bit denominato 'flags'; spesso 'flags' è
1046 un'alternativa molto più leggibile se si hanno valori costanti per true/false.
1048 Detto ciò, un uso parsimonioso di bool nelle strutture dati e negli argomenti
1049 può migliorare la leggibilità.
1051 18) Non reinventate le macro del kernel
1052 ---------------------------------------
1054 Il file di intestazione include/linux/kernel.h contiene un certo numero
1055 di macro che dovreste usare piuttosto che implementarne una qualche variante.
1056 Per esempio, se dovete calcolare la lunghezza di un vettore, sfruttate la
1061 #define ARRAY_SIZE(x) (sizeof(x) / sizeof((x)[0]))
1063 Analogamente, se dovete calcolare la dimensione di un qualche campo di una
1068 #define sizeof_field(t, f) (sizeof(((t*)0)->f))
1070 Ci sono anche le macro min() e max() che, se vi serve, effettuano un controllo
1071 rigido sui tipi. Sentitevi liberi di leggere attentamente questo file
1072 d'intestazione per scoprire cos'altro è stato definito che non dovreste
1073 reinventare nel vostro codice.
1075 19) Linee di configurazione degli editor e altre schifezze
1076 -----------------------------------------------------------
1078 Alcuni editor possono interpretare dei parametri di configurazione integrati
1079 nei file sorgenti e indicati con dai marcatori speciali. Per esempio, emacs
1080 interpreta le linee marcate nel seguente modo:
1092 compile-command: "gcc -DMAGIC_DEBUG_FLAG foo.c"
1096 Vim interpreta i marcatori come questi:
1100 /* vim:set sw=8 noet */
1102 Non includete nessuna di queste cose nei file sorgenti. Le persone hanno le
1103 proprie configurazioni personali per l'editor, e i vostri sorgenti non
1104 dovrebbero sovrascrivergliele. Questo vale anche per i marcatori
1105 d'indentazione e di modalità d'uso. Le persone potrebbero aver configurato una
1106 modalità su misura, oppure potrebbero avere qualche altra magia per far
1107 funzionare bene l'indentazione.
1112 Nel codice specifico per un'architettura, potreste aver bisogno di codice
1113 *inline assembly* per interfacciarvi col processore o con una funzionalità
1114 specifica della piattaforma. Non esitate a farlo quando è necessario.
1115 Comunque, non usatele gratuitamente quando il C può fare la stessa cosa.
1116 Potete e dovreste punzecchiare l'hardware in C quando è possibile.
1118 Considerate la scrittura di una semplice funzione che racchiude pezzi comuni
1119 di codice assembler piuttosto che continuare a riscrivere delle piccole
1120 varianti. Ricordatevi che l' *inline assembly* può utilizzare i parametri C.
1122 Il codice assembler più corposo e non banale dovrebbe andare nei file .S,
1123 coi rispettivi prototipi C definiti nei file d'intestazione. I prototipi C
1124 per le funzioni assembler dovrebbero usare ``asmlinkage``.
1126 Potreste aver bisogno di marcare il vostro codice asm come volatile al fine
1127 d'evitare che GCC lo rimuova quando pensa che non ci siano effetti collaterali.
1128 Non c'è sempre bisogno di farlo, e farlo quando non serve limita le
1131 Quando scrivete una singola espressione *inline assembly* contenente più
1132 istruzioni, mettete ognuna di queste istruzioni in una stringa e riga diversa;
1133 ad eccezione dell'ultima stringa/istruzione, ognuna deve terminare con ``\n\t``
1134 al fine di allineare correttamente l'assembler che verrà generato:
1138 asm ("magic %reg1, #42\n\t"
1139 "more_magic %reg2, %reg3"
1140 : /* outputs */ : /* inputs */ : /* clobbers */);
1142 21) Compilazione sotto condizione
1143 ---------------------------------
1145 Ovunque sia possibile, non usate le direttive condizionali del preprocessore
1146 (#if, #ifdef) nei file .c; farlo rende il codice difficile da leggere e da
1147 seguire. Invece, usate queste direttive nei file d'intestazione per definire
1148 le funzioni usate nei file .c, fornendo i relativi stub nel caso #else,
1149 e quindi chiamate queste funzioni senza condizioni di preprocessore. Il
1150 compilatore non produrrà alcun codice per le funzioni stub, produrrà gli
1151 stessi risultati, e la logica rimarrà semplice da seguire.
1153 È preferibile non compilare intere funzioni piuttosto che porzioni d'esse o
1154 porzioni d'espressioni. Piuttosto che mettere una ifdef in un'espressione,
1155 fattorizzate parte dell'espressione, o interamente, in funzioni e applicate
1156 la direttiva condizionale su di esse.
1158 Se avete una variabile o funzione che potrebbe non essere usata in alcune
1159 configurazioni, e quindi il compilatore potrebbe avvisarvi circa la definizione
1160 inutilizzata, marcate questa definizione come __maybe_unused piuttosto che
1161 racchiuderla in una direttiva condizionale del preprocessore. (Comunque,
1162 se una variabile o funzione è *sempre* inutilizzata, rimuovetela).
1164 Nel codice, dov'è possibile, usate la macro IS_ENABLED per convertire i
1165 simboli Kconfig in espressioni booleane C, e quindi usatela nelle classiche
1170 if (IS_ENABLED(CONFIG_SOMETHING)) {
1174 Il compilatore valuterà la condizione come costante (constant-fold), e quindi
1175 includerà o escluderà il blocco di codice come se fosse in un #ifdef, quindi
1176 non ne aumenterà il tempo di esecuzione. Tuttavia, questo permette al
1177 compilatore C di vedere il codice nel blocco condizionale e verificarne la
1178 correttezza (sintassi, tipi, riferimenti ai simboli, eccetera). Quindi
1179 dovete comunque utilizzare #ifdef se il codice nel blocco condizionale esiste
1180 solo quando la condizione è soddisfatta.
1182 Alla fine di un blocco corposo di #if o #ifdef (più di alcune linee),
1183 mettete un commento sulla stessa riga di #endif, annotando la condizione
1184 che termina. Per esempio:
1188 #ifdef CONFIG_SOMETHING
1190 #endif /* CONFIG_SOMETHING */
1192 Appendice I) riferimenti
1193 ------------------------
1195 The C Programming Language, Second Edition
1196 by Brian W. Kernighan and Dennis M. Ritchie.
1197 Prentice Hall, Inc., 1988.
1198 ISBN 0-13-110362-8 (paperback), 0-13-110370-9 (hardback).
1200 The Practice of Programming
1201 by Brian W. Kernighan and Rob Pike.
1202 Addison-Wesley, Inc., 1999.
1205 Manuali GNU - nei casi in cui sono compatibili con K&R e questo documento -
1206 per indent, cpp, gcc e i suoi dettagli interni, tutto disponibile qui
1207 http://www.gnu.org/manual/
1209 WG14 è il gruppo internazionale di standardizzazione per il linguaggio C,
1210 URL: http://www.open-std.org/JTC1/SC22/WG14/
1212 Kernel process/coding-style.rst, by greg@kroah.com at OLS 2002:
1213 http://www.kroah.com/linux/talks/ols_2002_kernel_codingstyle_talk/html/