coding-style.rst

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