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 né mettete più assegnamenti sulla stessa riga. Lo stile del kernel
79 è ultrasemplice. Evitate espressioni intricate.
81 Al di fuori dei commenti, della documentazione ed escludendo i Kconfig, gli
82 spazi non vengono mai usati per l'indentazione, e l'esempio qui sopra è
85 Procuratevi un buon editor di testo e non lasciate spazi bianchi alla fine
89 2) Spezzare righe lunghe e stringhe
90 -----------------------------------
92 Lo stile del codice riguarda la leggibilità e la manutenibilità utilizzando
95 Il limite delle righe è di 80 colonne e questo e un limite fortemente
98 Espressioni più lunghe di 80 colonne saranno spezzettate in pezzi più piccoli,
99 a meno che eccedere le 80 colonne non aiuti ad aumentare la leggibilità senza
100 nascondere informazioni. I pezzi derivati sono sostanzialmente più corti degli
101 originali e vengono posizionati più a destra. Lo stesso si applica, nei file
102 d'intestazione, alle funzioni con una lista di argomenti molto lunga. Tuttavia,
103 non spezzettate mai le stringhe visibili agli utenti come i messaggi di
104 printk, questo perché inibireste la possibilità d'utilizzare grep per cercarle.
106 3) Posizionamento di parentesi graffe e spazi
107 ---------------------------------------------
109 Un altro problema che s'affronta sempre quando si parla di stile in C è
110 il posizionamento delle parentesi graffe. Al contrario della dimensione
111 dell'indentazione, non ci sono motivi tecnici sulla base dei quali scegliere
112 una strategia di posizionamento o un'altra; ma il modo qui preferito,
113 come mostratoci dai profeti Kernighan e Ritchie, è quello di
114 posizionare la parentesi graffa di apertura per ultima sulla riga, e quella
115 di chiusura per prima su una nuova riga, così:
123 Questo è valido per tutte le espressioni che non siano funzioni (if, switch,
124 for, while, do). Per esempio:
139 Tuttavia, c'è il caso speciale, le funzioni: queste hanno la parentesi graffa
140 di apertura all'inizio della riga successiva, quindi:
149 Eretici da tutto il mondo affermano che questa incoerenza è ...
150 insomma ... incoerente, ma tutte le persone ragionevoli sanno che (a)
151 K&R hanno **ragione** e (b) K&R hanno ragione. A parte questo, le funzioni
152 sono comunque speciali (non potete annidarle in C).
154 Notate che la graffa di chiusura è da sola su una riga propria, ad
155 **eccezione** di quei casi dove è seguita dalla continuazione della stessa
156 espressione, in pratica ``while`` nell'espressione do-while, oppure ``else``
157 nell'espressione if-else, come questo:
179 Inoltre, notate che questo posizionamento delle graffe minimizza il numero
180 di righe vuote senza perdere di leggibilità. In questo modo, dato che le
181 righe sul vostro schermo non sono una risorsa illimitata (pensate ad uno
182 terminale con 25 righe), avrete delle righe vuote da riempire con dei
185 Non usate inutilmente le graffe dove una singola espressione è sufficiente.
201 Questo non vale nel caso in cui solo un ramo dell'espressione if-else
202 contiene una sola espressione; in quest'ultimo caso usate le graffe per
214 Inoltre, usate le graffe se un ciclo contiene più di una semplice istruzione:
226 Lo stile del kernel Linux per quanto riguarda gli spazi, dipende
227 (principalmente) dalle funzioni e dalle parole chiave. Usate una spazio dopo
228 (quasi tutte) le parole chiave. L'eccezioni più evidenti sono sizeof, typeof,
229 alignof, e __attribute__, il cui aspetto è molto simile a quello delle
230 funzioni (e in Linux, solitamente, sono usate con le parentesi, anche se il
231 linguaggio non lo richiede; come ``sizeof info`` dopo aver dichiarato
232 ``struct fileinfo info``).
234 Quindi utilizzate uno spazio dopo le seguenti parole chiave::
236 if, switch, case, for, do, while
238 ma non con sizeof, typeof, alignof, o __attribute__. Ad esempio,
243 s = sizeof(struct file);
245 Non aggiungete spazi attorno (dentro) ad un'espressione fra parentesi. Questo
246 esempio è **brutto**:
251 s = sizeof( struct file );
253 Quando dichiarate un puntatore ad una variabile o una funzione che ritorna un
254 puntatore, il posto suggerito per l'asterisco ``*`` è adiacente al nome della
255 variabile o della funzione, e non adiacente al nome del tipo. Esempi:
261 unsigned long long memparse(char *ptr, char **retptr);
262 char *match_strdup(substring_t *s);
264 Usate uno spazio attorno (da ogni parte) alla maggior parte degli operatori
265 binari o ternari, come i seguenti::
267 = + - < > * / % | & ^ <= >= == != ? :
269 ma non mettete spazi dopo gli operatori unari::
271 & * + - ~ ! sizeof typeof alignof __attribute__ defined
273 nessuno spazio dopo l'operatore unario suffisso di incremento o decremento::
277 nessuno spazio dopo l'operatore unario prefisso di incremento o decremento::
281 e nessuno spazio attorno agli operatori dei membri di una struttura ``.`` e
284 Non lasciate spazi bianchi alla fine delle righe. Alcuni editor con
285 l'indentazione ``furba`` inseriranno gli spazi bianchi all'inizio di una nuova
286 riga in modo appropriato, quindi potrete scrivere la riga di codice successiva
287 immediatamente. Tuttavia, alcuni di questi stessi editor non rimuovono
288 questi spazi bianchi quando non scrivete nulla sulla nuova riga, ad esempio
289 perché volete lasciare una riga vuota. Il risultato è che finirete per avere
290 delle righe che contengono spazi bianchi in coda.
292 Git vi avviserà delle modifiche che aggiungono questi spazi vuoti di fine riga,
293 e può opzionalmente rimuoverli per conto vostro; tuttavia, se state applicando
294 una serie di modifiche, questo potrebbe far fallire delle modifiche successive
295 perché il contesto delle righe verrà cambiato.
300 C è un linguaggio spartano, e così dovrebbero esserlo i vostri nomi. Al
301 contrario dei programmatori Modula-2 o Pascal, i programmatori C non usano
302 nomi graziosi come ThisVariableIsATemporaryCounter. Un programmatore C
303 chiamerebbe questa variabile ``tmp``, che è molto più facile da scrivere e
304 non è una delle più difficili da capire.
306 TUTTAVIA, nonostante i nomi con notazione mista siano da condannare, i nomi
307 descrittivi per variabili globali sono un dovere. Chiamare una funzione
308 globale ``pippo`` è un insulto.
310 Le variabili GLOBALI (da usare solo se vi servono **davvero**) devono avere
311 dei nomi descrittivi, così come le funzioni globali. Se avete una funzione
312 che conta gli utenti attivi, dovreste chiamarla ``count_active_users()`` o
313 qualcosa di simile, **non** dovreste chiamarla ``cntusr()``.
315 Codificare il tipo di funzione nel suo nome (quella cosa chiamata notazione
316 ungherese) fa male al cervello - il compilatore conosce comunque il tipo e
317 può verificarli, e inoltre confonde i programmatori. Non c'è da
318 sorprendersi che MicroSoft faccia programmi bacati.
320 Le variabili LOCALI dovrebbero avere nomi corti, e significativi. Se avete
321 un qualsiasi contatore di ciclo, probabilmente sarà chiamato ``i``.
322 Chiamarlo ``loop_counter`` non è produttivo, non ci sono possibilità che
323 ``i`` possa non essere capito. Analogamente, ``tmp`` può essere una qualsiasi
324 variabile che viene usata per salvare temporaneamente un valore.
326 Se avete paura di fare casino coi nomi delle vostre variabili locali, allora
327 avete un altro problema che è chiamato sindrome dello squilibrio dell'ormone
328 della crescita delle funzioni. Vedere il capitolo 6 (funzioni).
330 5) Definizione di tipi (typedef)
331 --------------------------------
333 Per favore non usate cose come ``vps_t``.
334 Usare il typedef per strutture e puntatori è uno **sbaglio**. Quando vedete:
340 nei sorgenti, cosa significa?
345 struct virtual_container *a;
347 potreste dire cos'è effettivamente ``a``.
349 Molte persone pensano che la definizione dei tipi ``migliori la leggibilità``.
350 Non molto. Sono utili per:
352 (a) gli oggetti completamente opachi (dove typedef viene proprio usato allo
353 scopo di **nascondere** cosa sia davvero l'oggetto).
355 Esempio: ``pte_t`` eccetera sono oggetti opachi che potete usare solamente
356 con le loro funzioni accessorie.
359 Gli oggetti opachi e le ``funzioni accessorie`` non sono, di per se,
360 una bella cosa. Il motivo per cui abbiamo cose come pte_t eccetera è
361 che davvero non c'è alcuna informazione portabile.
363 (b) i tipi chiaramente interi, dove l'astrazione **aiuta** ad evitare
364 confusione sul fatto che siano ``int`` oppure ``long``.
366 u8/u16/u32 sono typedef perfettamente accettabili, anche se ricadono
367 nella categoria (d) piuttosto che in questa.
371 Ancora - dev'esserci una **ragione** per farlo. Se qualcosa è
372 ``unsigned long``, non c'è alcun bisogno di avere:
374 typedef unsigned long myfalgs_t;
376 ma se ci sono chiare circostanze in cui potrebbe essere ``unsigned int``
377 e in altre configurazioni ``unsigned long``, allora certamente typedef
380 (c) quando di rado create letteralmente dei **nuovi** tipi su cui effettuare
383 (d) circostanze eccezionali, in cui si definiscono nuovi tipi identici a
384 quelli definiti dallo standard C99.
386 Nonostante ci voglia poco tempo per abituare occhi e cervello all'uso dei
387 tipi standard come ``uint32_t``, alcune persone ne obiettano l'uso.
389 Perciò, i tipi specifici di Linux ``u8/u16/u32/u64`` e i loro equivalenti
390 con segno, identici ai tipi standard, sono permessi- tuttavia, non sono
391 obbligatori per il nuovo codice.
393 (e) i tipi sicuri nella spazio utente.
395 In alcune strutture dati visibili dallo spazio utente non possiamo
396 richiedere l'uso dei tipi C99 e nemmeno i vari ``u32`` descritti prima.
397 Perciò, utilizziamo __u32 e tipi simili in tutte le strutture dati
398 condivise con lo spazio utente.
400 Magari ci sono altri casi validi, ma la regola di base dovrebbe essere di
401 non usare MAI MAI un typedef a meno che non rientri in una delle regole
404 In generale, un puntatore, o una struttura a cui si ha accesso diretto in
405 modo ragionevole, non dovrebbero **mai** essere definite con un typedef.
410 Le funzioni dovrebbero essere brevi e carine, e fare una cosa sola. Dovrebbero
411 occupare uno o due schermi di testo (come tutti sappiamo, la dimensione
412 di uno schermo secondo ISO/ANSI è di 80x24), e fare una cosa sola e bene.
414 La massima lunghezza di una funziona è inversamente proporzionale alla sua
415 complessità e al livello di indentazione di quella funzione. Quindi, se avete
416 una funzione che è concettualmente semplice ma che è implementata come un
417 lunga (ma semplice) sequenza di caso-istruzione, dove avete molte piccole cose
418 per molti casi differenti, allora va bene avere funzioni più lunghe.
420 Comunque, se avete una funzione complessa e sospettate che uno studente
421 non particolarmente dotato del primo anno delle scuole superiori potrebbe
422 non capire cosa faccia la funzione, allora dovreste attenervi strettamente ai
423 limiti. Usate funzioni di supporto con nomi descrittivi (potete chiedere al
424 compilatore di renderle inline se credete che sia necessario per le
425 prestazioni, e probabilmente farà un lavoro migliore di quanto avreste potuto
428 Un'altra misura delle funzioni sono il numero di variabili locali. Non
429 dovrebbero eccedere le 5-10, oppure state sbagliando qualcosa. Ripensate la
430 funzione, e dividetela in pezzettini. Generalmente, un cervello umano può
431 seguire facilmente circa 7 cose diverse, di più lo confonderebbe. Lo sai
432 d'essere brillante, ma magari vorresti riuscire a capire cos'avevi fatto due
435 Nei file sorgenti, separate le funzioni con una riga vuota. Se la funzione è
436 esportata, la macro **EXPORT** per questa funzione deve seguire immediatamente
437 la riga della parentesi graffa di chiusura. Ad esempio:
441 int system_is_up(void)
443 return system_state == SYSTEM_RUNNING;
445 EXPORT_SYMBOL(system_is_up);
447 Nei prototipi di funzione, includete i nomi dei parametri e i loro tipi.
448 Nonostante questo non sia richiesto dal linguaggio C, in Linux viene preferito
449 perché è un modo semplice per aggiungere informazioni importanti per il
452 7) Centralizzare il ritorno delle funzioni
453 ------------------------------------------
455 Sebbene sia deprecata da molte persone, l'istruzione goto è impiegata di
456 frequente dai compilatori sotto forma di salto incondizionato.
458 L'istruzione goto diventa utile quando una funzione ha punti d'uscita multipli
459 e vanno eseguite alcune procedure di pulizia in comune. Se non è necessario
460 pulire alcunché, allora ritornate direttamente.
462 Assegnate un nome all'etichetta di modo che suggerisca cosa fa la goto o
463 perché esiste. Un esempio di un buon nome potrebbe essere ``out_free_buffer:``
464 se la goto libera (free) un ``buffer``. Evitate l'uso di nomi GW-BASIC come
465 ``err1:`` ed ``err2:``, potreste doverli riordinare se aggiungete o rimuovete
466 punti d'uscita, e inoltre rende difficile verificarne la correttezza.
468 I motivo per usare le goto sono:
470 - i salti incondizionati sono più facili da capire e seguire
471 - l'annidamento si riduce
472 - si evita di dimenticare, per errore, di aggiornare un singolo punto d'uscita
473 - aiuta il compilatore ad ottimizzare il codice ridondante ;)
482 buffer = kmalloc(SIZE, GFP_KERNEL);
491 goto out_free_buffer;
499 Un baco abbastanza comune di cui bisogna prendere nota è il ``one err bugs``
500 che assomiglia a questo:
509 Il baco in questo codice è che in alcuni punti d'uscita la variabile ``foo`` è
510 NULL. Normalmente si corregge questo baco dividendo la gestione dell'errore in
511 due parti ``err_free_bar:`` e ``err_free_foo:``:
521 Idealmente, dovreste simulare condizioni d'errore per verificare i vostri
528 I commenti sono una buona cosa, ma c'è anche il rischio di esagerare. MAI
529 spiegare COME funziona il vostro codice in un commento: è molto meglio
530 scrivere il codice di modo che il suo funzionamento sia ovvio, inoltre
531 spiegare codice scritto male è una perdita di tempo.
533 Solitamente, i commenti devono dire COSA fa il codice, e non COME lo fa.
534 Inoltre, cercate di evitare i commenti nel corpo della funzione: se la
535 funzione è così complessa che dovete commentarla a pezzi, allora dovreste
536 tornare al punto 6 per un momento. Potete mettere dei piccoli commenti per
537 annotare o avvisare il lettore circa un qualcosa di particolarmente arguto
538 (o brutto), ma cercate di non esagerare. Invece, mettete i commenti in
539 testa alla funzione spiegando alle persone cosa fa, e possibilmente anche
542 Per favore, quando commentate una funzione dell'API del kernel usate il
543 formato kernel-doc. Per maggiori dettagli, leggete i file in
544 :ref::ref:`Documentation/translations/it_IT/doc-guide/ <it_doc_guide>` e in
545 ``script/kernel-doc``.
547 Lo stile preferito per i commenti più lunghi (multi-riga) è:
552 * This is the preferred style for multi-line
553 * comments in the Linux kernel source code.
554 * Please use it consistently.
556 * Description: A column of asterisks on the left side,
557 * with beginning and ending almost-blank lines.
560 Per i file in net/ e in drivers/net/ lo stile preferito per i commenti
561 più lunghi (multi-riga) è leggermente diverso.
565 /* The preferred comment style for files in net/ and drivers/net
568 * It is nearly the same as the generally preferred comment style,
569 * but there is no initial almost-blank line.
572 È anche importante commentare i dati, sia per i tipi base che per tipi
573 derivati. A questo scopo, dichiarate un dato per riga (niente virgole
574 per una dichiarazione multipla). Questo vi lascerà spazio per un piccolo
575 commento per spiegarne l'uso.
578 9) Avete fatto un pasticcio
579 ---------------------------
581 Va bene, li facciamo tutti. Probabilmente vi è stato detto dal vostro
582 aiutante Unix di fiducia che ``GNU emacs`` formatta automaticamente il
583 codice C per conto vostro, e avete notato che sì, in effetti lo fa, ma che
584 i modi predefiniti non sono proprio allettanti (infatti, sono peggio che
585 premere tasti a caso - un numero infinito di scimmie che scrivono in
586 GNU emacs non faranno mai un buon programma).
588 Quindi, potete sbarazzarvi di GNU emacs, o riconfigurarlo con valori più
589 sensati. Per fare quest'ultima cosa, potete appiccicare il codice che
590 segue nel vostro file .emacs:
594 (defun c-lineup-arglist-tabs-only (ignored)
595 "Line up argument lists by tabs, not spaces"
596 (let* ((anchor (c-langelem-pos c-syntactic-element))
597 (column (c-langelem-2nd-pos c-syntactic-element))
598 (offset (- (1+ column) anchor))
599 (steps (floor offset c-basic-offset)))
603 (add-hook 'c-mode-common-hook
608 '("linux" (c-offsets-alist
609 (arglist-cont-nonempty
611 c-lineup-arglist-tabs-only))))))
613 (add-hook 'c-mode-hook
615 (let ((filename (buffer-file-name)))
616 ;; Enable kernel mode for the appropriate files
618 (string-match (expand-file-name "~/src/linux-trees")
620 (setq indent-tabs-mode t)
621 (setq show-trailing-whitespace t)
622 (c-set-style "linux-tabs-only")))))
624 Questo farà funzionare meglio emacs con lo stile del kernel per i file che
625 si trovano nella cartella ``~/src/linux-trees``.
627 Ma anche se doveste fallire nell'ottenere una formattazione sensata in emacs
628 non tutto è perduto: usate ``indent``.
630 Ora, ancora, GNU indent ha la stessa configurazione decerebrata di GNU emacs,
631 ed è per questo che dovete passargli alcune opzioni da riga di comando.
632 Tuttavia, non è così terribile, perché perfino i creatori di GNU indent
633 riconoscono l'autorità di K&R (le persone del progetto GNU non sono cattive,
634 sono solo mal indirizzate sull'argomento), quindi date ad indent le opzioni
635 ``-kr -i8`` (che significa ``K&R, 8 caratteri di indentazione``), o utilizzate
636 ``scripts/Lindent`` che indenterà usando l'ultimo stile.
638 ``indent`` ha un sacco di opzioni, e specialmente quando si tratta di
639 riformattare i commenti dovreste dare un'occhiata alle pagine man.
640 Ma ricordatevi: ``indent`` non è un correttore per una cattiva programmazione.
642 Da notare che potete utilizzare anche ``clang-format`` per aiutarvi con queste
643 regole, per riformattare rapidamente ad automaticamente alcune parti del
644 vostro codice, e per revisionare interi file al fine di identificare errori
645 di stile, refusi e possibilmente anche delle migliorie. È anche utile per
646 ordinare gli ``#include``, per allineare variabili/macro, per ridistribuire
647 il testo e altre cose simili.
648 Per maggiori dettagli, consultate il file
649 :ref:`Documentation/translations/it_IT/process/clang-format.rst <it_clangformat>`.
652 10) File di configurazione Kconfig
653 ----------------------------------
655 Per tutti i file di configurazione Kconfig* che si possono trovare nei
656 sorgenti, l'indentazione è un po' differente. Le linee dopo un ``config``
657 sono indentate con un tab, mentre il testo descrittivo è indentato di
658 ulteriori due spazi. Esempio::
661 bool "Auditing support"
664 Enable auditing infrastructure that can be used with another
665 kernel subsystem, such as SELinux (which requires this for
666 logging of avc messages output). Does not do system-call
667 auditing without CONFIG_AUDITSYSCALL.
669 Le funzionalità davvero pericolose (per esempio il supporto alla scrittura
670 per certi filesystem) dovrebbero essere dichiarate chiaramente come tali
671 nella stringa di titolo::
674 bool "ADFS write support (DANGEROUS)"
678 Per la documentazione completa sui file di configurazione, consultate
679 il documento Documentation/translations/it_IT/kbuild/kconfig-language.txt
685 Le strutture dati che hanno una visibilità superiore al contesto del
686 singolo thread in cui vengono create e distrutte, dovrebbero sempre
687 avere un contatore di riferimenti. Nel kernel non esiste un
688 *garbage collector* (e fuori dal kernel i *garbage collector* sono lenti
689 e inefficienti), questo significa che **dovete** assolutamente avere un
690 contatore di riferimenti per ogni cosa che usate.
692 Avere un contatore di riferimenti significa che potete evitare la
693 sincronizzazione e permette a più utenti di accedere alla struttura dati
694 in parallelo - e non doversi preoccupare di una struttura dati che
695 improvvisamente sparisce dalla loro vista perché il loro processo dormiva
696 o stava facendo altro per un attimo.
698 Da notare che la sincronizzazione **non** si sostituisce al conteggio dei
699 riferimenti. La sincronizzazione ha lo scopo di mantenere le strutture
700 dati coerenti, mentre il conteggio dei riferimenti è una tecnica di gestione
701 della memoria. Solitamente servono entrambe le cose, e non vanno confuse fra
704 Quando si hanno diverse classi di utenti, le strutture dati possono avere
705 due livelli di contatori di riferimenti. Il contatore di classe conta
706 il numero dei suoi utenti, e il contatore globale viene decrementato una
707 sola volta quando il contatore di classe va a zero.
709 Un esempio di questo tipo di conteggio dei riferimenti multi-livello può
710 essere trovato nella gestore della memoria (``struct mm_sturct``: mm_user e
711 mm_count), e nel codice dei filesystem (``struct super_block``: s_count e
714 Ricordatevi: se un altro thread può trovare la vostra struttura dati, e non
715 avete un contatore di riferimenti per essa, quasi certamente avete un baco.
717 12) Macro, enumerati e RTL
718 ---------------------------
720 I nomi delle macro che definiscono delle costanti e le etichette degli
721 enumerati sono scritte in maiuscolo.
725 #define CONSTANT 0x12345
727 Gli enumerati sono da preferire quando si definiscono molte costanti correlate.
729 I nomi delle macro in MAIUSCOLO sono preferibili ma le macro che assomigliano
730 a delle funzioni possono essere scritte in minuscolo.
732 Generalmente, le funzioni inline sono preferibili rispetto alle macro che
735 Le macro che contengono più istruzioni dovrebbero essere sempre chiuse in un
740 #define macrofun(a, b, c) \
746 Cose da evitare quando si usano le macro:
748 1) le macro che hanno effetti sul flusso del codice:
758 sono **proprio** una pessima idea. Sembra una chiamata a funzione ma termina
759 la funzione chiamante; non cercate di rompere il decodificatore interno di
762 2) le macro che dipendono dall'uso di una variabile locale con un nome magico:
766 #define FOO(val) bar(index, val)
768 potrebbe sembrare una bella cosa, ma è dannatamente confusionario quando uno
769 legge il codice e potrebbe romperlo con una cambiamento che sembra innocente.
771 3) le macro con argomenti che sono utilizzati come l-values; questo potrebbe
772 ritorcervisi contro se qualcuno, per esempio, trasforma FOO in una funzione
775 4) dimenticatevi delle precedenze: le macro che definiscono espressioni devono
776 essere racchiuse fra parentesi. State attenti a problemi simili con le macro
781 #define CONSTANT 0x4000
782 #define CONSTEXP (CONSTANT | 3)
784 5) collisione nello spazio dei nomi quando si definisce una variabile locale in
785 una macro che sembra una funzione:
796 ret è un nome comune per una variabile locale - __foo_ret difficilmente
797 andrà in conflitto con una variabile già esistente.
799 Il manuale di cpp si occupa esaustivamente delle macro. Il manuale di sviluppo
800 di gcc copre anche l'RTL che viene usato frequentemente nel kernel per il
801 linguaggio assembler.
803 13) Visualizzare i messaggi del kernel
804 --------------------------------------
806 Agli sviluppatori del kernel piace essere visti come dotti. Tenete un occhio
807 di riguardo per l'ortografia e farete una belle figura. In inglese, evitate
808 l'uso di parole mozzate come ``dont``: usate ``do not`` oppure ``don't``.
809 Scrivete messaggi concisi, chiari, e inequivocabili.
811 I messaggi del kernel non devono terminare con un punto fermo.
813 Scrivere i numeri fra parentesi (%d) non migliora alcunché e per questo
814 dovrebbero essere evitati.
816 Ci sono alcune macro per la diagnostica in <linux/device.h> che dovreste
817 usare per assicurarvi che i messaggi vengano associati correttamente ai
818 dispositivi e ai driver, e che siano etichettati correttamente: dev_err(),
819 dev_warn(), dev_info(), e così via. Per messaggi che non sono associati ad
820 alcun dispositivo, <linux/printk.h> definisce pr_info(), pr_warn(), pr_err(),
823 Tirar fuori un buon messaggio di debug può essere una vera sfida; e quando
824 l'avete può essere d'enorme aiuto per risolvere problemi da remoto.
825 Tuttavia, i messaggi di debug sono gestiti differentemente rispetto agli
826 altri. Le funzioni pr_XXX() stampano incondizionatamente ma pr_debug() no;
827 essa non viene compilata nella configurazione predefinita, a meno che
828 DEBUG o CONFIG_DYNAMIC_DEBUG non vengono impostati. Questo vale anche per
829 dev_dbg() e in aggiunta VERBOSE_DEBUG per aggiungere i messaggi dev_vdbg().
831 Molti sottosistemi hanno delle opzioni di debug in Kconfig che aggiungono
832 -DDEBUG nei corrispettivi Makefile, e in altri casi aggiungono #define DEBUG
833 in specifici file. Infine, quando un messaggio di debug dev'essere stampato
834 incondizionatamente, per esempio perché siete già in una sezione di debug
835 racchiusa in #ifdef, potete usare printk(KERN_DEBUG ...).
837 14) Assegnare memoria
838 ---------------------
840 Il kernel fornisce i seguenti assegnatori ad uso generico:
841 kmalloc(), kzalloc(), kmalloc_array(), kcalloc(), vmalloc(), e vzalloc().
842 Per maggiori informazioni, consultate la documentazione dell'API.
844 Il modo preferito per passare la dimensione di una struttura è il seguente:
848 p = kmalloc(sizeof(*p), ...);
850 La forma alternativa, dove il nome della struttura viene scritto interamente,
851 peggiora la leggibilità e introduce possibili bachi quando il tipo di
852 puntatore cambia tipo ma il corrispondente sizeof non viene aggiornato.
854 Il valore di ritorno è un puntatore void, effettuare un cast su di esso è
855 ridondante. La conversione fra un puntatore void e un qualsiasi altro tipo
856 di puntatore è garantito dal linguaggio di programmazione C.
858 Il modo preferito per assegnare un vettore è il seguente:
862 p = kmalloc_array(n, sizeof(...), ...);
864 Il modo preferito per assegnare un vettore a zero è il seguente:
868 p = kcalloc(n, sizeof(...), ...);
870 Entrambe verificano la condizione di overflow per la dimensione
871 d'assegnamento n * sizeof(...), se accade ritorneranno NULL.
876 Sembra che ci sia la percezione errata che gcc abbia una qualche magica
877 opzione "rendimi più veloce" chiamata ``inline``. In alcuni casi l'uso di
878 inline è appropriato (per esempio in sostituzione delle macro, vedi
879 capitolo 12), ma molto spesso non lo è. L'uso abbondante della parola chiave
880 inline porta ad avere un kernel più grande, che si traduce in un sistema nel
881 suo complesso più lento per via di una cache per le istruzioni della CPU più
882 grande e poi semplicemente perché ci sarà meno spazio disponibile per una
883 pagina di cache. Pensateci un attimo; una fallimento nella cache causa una
884 ricerca su disco che può tranquillamente richiedere 5 millisecondi. Ci sono
885 TANTI cicli di CPU che potrebbero essere usati in questi 5 millisecondi.
887 Spesso le persone dicono che aggiungere inline a delle funzioni dichiarate
888 static e utilizzare una sola volta è sempre una scelta vincente perché non
889 ci sono altri compromessi. Questo è tecnicamente vero ma gcc è in grado di
890 trasformare automaticamente queste funzioni in inline; i problemi di
891 manutenzione del codice per rimuovere gli inline quando compare un secondo
892 utente surclassano il potenziale vantaggio nel suggerire a gcc di fare una
893 cosa che avrebbe fatto comunque.
895 16) Nomi e valori di ritorno delle funzioni
896 -------------------------------------------
898 Le funzioni possono ritornare diversi tipi di valori, e uno dei più comuni
899 è quel valore che indica se una funzione ha completato con successo o meno.
900 Questo valore può essere rappresentato come un codice di errore intero
901 (-Exxx = fallimento, 0 = successo) oppure un booleano di successo
902 (0 = fallimento, non-zero = successo).
904 Mischiare questi due tipi di rappresentazioni è un terreno fertile per
905 i bachi più insidiosi. Se il linguaggio C includesse una forte distinzione
906 fra gli interi e i booleani, allora il compilatore potrebbe trovare questi
907 errori per conto nostro ... ma questo non c'è. Per evitare di imbattersi
908 in questo tipo di baco, seguite sempre la seguente convenzione::
910 Se il nome di una funzione è un'azione o un comando imperativo,
911 essa dovrebbe ritornare un codice di errore intero. Se il nome
912 è un predicato, la funzione dovrebbe ritornare un booleano di
915 Per esempio, ``add work`` è un comando, e la funzione add_work() ritorna 0
916 in caso di successo o -EBUSY in caso di fallimento. Allo stesso modo,
917 ``PCI device present`` è un predicato, e la funzione pci_dev_present() ritorna
918 1 se trova il dispositivo corrispondente con successo, altrimenti 0.
920 Tutte le funzioni esportate (EXPORT) devono rispettare questa convenzione, e
921 così dovrebbero anche tutte le funzioni pubbliche. Le funzioni private
922 (static) possono non seguire questa convenzione, ma è comunque raccomandato
925 Le funzioni il cui valore di ritorno è il risultato di una computazione,
926 piuttosto che l'indicazione sul successo di tale computazione, non sono
927 soggette a questa regola. Solitamente si indicano gli errori ritornando un
928 qualche valore fuori dai limiti. Un tipico esempio è quello delle funzioni
929 che ritornano un puntatore; queste utilizzano NULL o ERR_PTR come meccanismo
930 di notifica degli errori.
932 17) Non reinventate le macro del kernel
933 ---------------------------------------
935 Il file di intestazione include/linux/kernel.h contiene un certo numero
936 di macro che dovreste usare piuttosto che implementarne una qualche variante.
937 Per esempio, se dovete calcolare la lunghezza di un vettore, sfruttate la
942 #define ARRAY_SIZE(x) (sizeof(x) / sizeof((x)[0]))
944 Analogamente, se dovete calcolare la dimensione di un qualche campo di una
949 #define FIELD_SIZEOF(t, f) (sizeof(((t*)0)->f))
951 Ci sono anche le macro min() e max() che, se vi serve, effettuano un controllo
952 rigido sui tipi. Sentitevi liberi di leggere attentamente questo file
953 d'intestazione per scoprire cos'altro è stato definito che non dovreste
954 reinventare nel vostro codice.
956 18) Linee di configurazione degli editor e altre schifezze
957 -----------------------------------------------------------
959 Alcuni editor possono interpretare dei parametri di configurazione integrati
960 nei file sorgenti e indicati con dai marcatori speciali. Per esempio, emacs
961 interpreta le linee marcate nel seguente modo:
973 compile-command: "gcc -DMAGIC_DEBUG_FLAG foo.c"
977 Vim interpreta i marcatori come questi:
981 /* vim:set sw=8 noet */
983 Non includete nessuna di queste cose nei file sorgenti. Le persone hanno le
984 proprie configurazioni personali per l'editor, e i vostri sorgenti non
985 dovrebbero sovrascrivergliele. Questo vale anche per i marcatori
986 d'indentazione e di modalità d'uso. Le persone potrebbero aver configurato una
987 modalità su misura, oppure potrebbero avere qualche altra magia per far
988 funzionare bene l'indentazione.
991 ---------------------
993 Nel codice specifico per un'architettura, potreste aver bisogno di codice
994 *inline assembly* per interfacciarvi col processore o con una funzionalità
995 specifica della piattaforma. Non esitate a farlo quando è necessario.
996 Comunque, non usatele gratuitamente quando il C può fare la stessa cosa.
997 Potete e dovreste punzecchiare l'hardware in C quando è possibile.
999 Considerate la scrittura di una semplice funzione che racchiude pezzi comuni
1000 di codice assembler piuttosto che continuare a riscrivere delle piccole
1001 varianti. Ricordatevi che l' *inline assembly* può utilizzare i parametri C.
1003 Il codice assembler più corposo e non banale dovrebbe andare nei file .S,
1004 coi rispettivi prototipi C definiti nei file d'intestazione. I prototipi C
1005 per le funzioni assembler dovrebbero usare ``asmlinkage``.
1007 Potreste aver bisogno di marcare il vostro codice asm come volatile al fine
1008 d'evitare che GCC lo rimuova quando pensa che non ci siano effetti collaterali.
1009 Non c'è sempre bisogno di farlo, e farlo quando non serve limita le
1012 Quando scrivete una singola espressione *inline assembly* contenente più
1013 istruzioni, mettete ognuna di queste istruzioni in una stringa e riga diversa;
1014 ad eccezione dell'ultima stringa/istruzione, ognuna deve terminare con ``\n\t``
1015 al fine di allineare correttamente l'assembler che verrà generato:
1019 asm ("magic %reg1, #42\n\t"
1020 "more_magic %reg2, %reg3"
1021 : /* outputs */ : /* inputs */ : /* clobbers */);
1023 20) Compilazione sotto condizione
1024 ---------------------------------
1026 Ovunque sia possibile, non usate le direttive condizionali del preprocessore
1027 (#if, #ifdef) nei file .c; farlo rende il codice difficile da leggere e da
1028 seguire. Invece, usate queste direttive nei file d'intestazione per definire
1029 le funzioni usate nei file .c, fornendo i relativi stub nel caso #else,
1030 e quindi chiamate queste funzioni senza condizioni di preprocessore. Il
1031 compilatore non produrrà alcun codice per le funzioni stub, produrrà gli
1032 stessi risultati, e la logica rimarrà semplice da seguire.
1034 È preferibile non compilare intere funzioni piuttosto che porzioni d'esse o
1035 porzioni d'espressioni. Piuttosto che mettere una ifdef in un'espressione,
1036 fattorizzate parte dell'espressione, o interamente, in funzioni e applicate
1037 la direttiva condizionale su di esse.
1039 Se avete una variabile o funzione che potrebbe non essere usata in alcune
1040 configurazioni, e quindi il compilatore potrebbe avvisarvi circa la definizione
1041 inutilizzata, marcate questa definizione come __maybe_used piuttosto che
1042 racchiuderla in una direttiva condizionale del preprocessore. (Comunque,
1043 se una variabile o funzione è *sempre* inutilizzata, rimuovetela).
1045 Nel codice, dov'è possibile, usate la macro IS_ENABLED per convertire i
1046 simboli Kconfig in espressioni booleane C, e quindi usatela nelle classiche
1051 if (IS_ENABLED(CONFIG_SOMETHING)) {
1055 Il compilatore valuterà la condizione come costante (constant-fold), e quindi
1056 includerà o escluderà il blocco di codice come se fosse in un #ifdef, quindi
1057 non ne aumenterà il tempo di esecuzione. Tuttavia, questo permette al
1058 compilatore C di vedere il codice nel blocco condizionale e verificarne la
1059 correttezza (sintassi, tipi, riferimenti ai simboli, eccetera). Quindi
1060 dovete comunque utilizzare #ifdef se il codice nel blocco condizionale esiste
1061 solo quando la condizione è soddisfatta.
1063 Alla fine di un blocco corposo di #if o #ifdef (più di alcune linee),
1064 mettete un commento sulla stessa riga di #endif, annotando la condizione
1065 che termina. Per esempio:
1069 #ifdef CONFIG_SOMETHING
1071 #endif /* CONFIG_SOMETHING */
1073 Appendice I) riferimenti
1074 ------------------------
1076 The C Programming Language, Second Edition
1077 by Brian W. Kernighan and Dennis M. Ritchie.
1078 Prentice Hall, Inc., 1988.
1079 ISBN 0-13-110362-8 (paperback), 0-13-110370-9 (hardback).
1081 The Practice of Programming
1082 by Brian W. Kernighan and Rob Pike.
1083 Addison-Wesley, Inc., 1999.
1086 Manuali GNU - nei casi in cui sono compatibili con K&R e questo documento -
1087 per indent, cpp, gcc e i suoi dettagli interni, tutto disponibile qui
1088 http://www.gnu.org/manual/
1090 WG14 è il gruppo internazionale di standardizzazione per il linguaggio C,
1091 URL: http://www.open-std.org/JTC1/SC22/WG14/
1093 Kernel process/coding-style.rst, by greg@kroah.com at OLS 2002:
1094 http://www.kroah.com/linux/talks/ols_2002_kernel_codingstyle_talk/html/