Documentation/translations/it_IT/process/4.Coding.rst

   1 .. include:: ../disclaimer-ita.rst
   2
   3 :Original: :ref:`Documentation/process/4.Coding.rst <development_coding>`
   4 :Translator: Alessia Mantegazza <amantegazza@vaga.pv.it>
   5
   6 .. _it_development_coding:
   7
   8 Scrivere codice corretto
   9 ========================
  10
  11 Nonostante ci sia molto da dire sul processo di creazione, sulla sua solidità
  12 e sul suo orientamento alla comunità, la prova di ogni progetto di sviluppo
  13 del kernel si trova nel codice stesso.  È il codice che sarà esaminato dagli
  14 altri sviluppatori ed inserito (o no) nel ramo principale. Quindi è la
  15 qualità di questo codice che determinerà il successo finale del progetto.
  16
  17 Questa sezione esaminerà il processo di codifica.  Inizieremo con uno sguardo
  18 sulle diverse casistiche nelle quali gli sviluppatori kernel possono
  19 sbagliare.  Poi, l'attenzione si sposterà verso "il fare le cose
  20 correttamente" e sugli strumenti che possono essere utili in questa missione.
  21
  22 Trappole
  23 --------
  24
  25 Lo stile del codice
  26 *******************
  27
  28 Il kernel ha da tempo delle norme sullo stile di codifica che sono descritte in
  29 :ref:`Documentation/translations/it_IT/process/coding-style.rst <codingstyle>`.
  30 Per la maggior parte del tempo, la politica descritta in quel file è stata
  31 praticamente informativa.  Ne risulta che ci sia una quantità sostanziale di
  32 codice nel kernel che non rispetta le linee guida relative allo stile.
  33 La presenza di quel codice conduce a due distinti pericoli per gli
  34 sviluppatori kernel.
  35
  36 Il primo di questi è credere che gli standard di codifica del kernel
  37 non sono importanti e possono non essere applicati.  La verità è che
  38 aggiungere nuovo codice al kernel è davvero difficile se questo non
  39 rispetta le norme; molti sviluppatori richiederanno che il codice sia
  40 riformulato prima che anche solo lo revisionino.  Una base di codice larga
  41 quanto il kernel richiede una certa uniformità, in modo da rendere possibile
  42 per gli sviluppatori una comprensione veloce di ogni sua parte.  Non ci sono,
  43 quindi, più spazi per un codice formattato alla carlona.
  44
  45 Occasionalmente, lo stile di codifica del kernel andrà in conflitto con lo
  46 stile richiesto da un datore di lavoro.  In alcuni casi, lo stile del kernel
  47 dovrà prevalere prima che il codice venga inserito.  Mettere il codice
  48 all'interno del kernel significa rinunciare a un certo grado di controllo
  49 in differenti modi - incluso il controllo sul come formattare il codice.
  50
  51 L’altra trappola è quella di pensare che il codice già presente nel kernel
  52 abbia urgentemente bisogno di essere sistemato.  Gli sviluppatori potrebbero
  53 iniziare a generare patch che correggono lo stile come modo per prendere
  54 famigliarità con il processo, o come modo per inserire i propri nomi nei
  55 changelog del kernel – o entrambe.  La comunità di sviluppo vede un attività
  56 di codifica puramente correttiva come "rumore"; queste attività riceveranno
  57 una fredda accoglienza.  Di conseguenza è meglio evitare questo tipo di patch.
  58 Mentre si lavora su un pezzo di codice è normale correggerne anche lo stile,
  59 ma le modifiche di stile non dovrebbero essere fatte fini a se stesse.
  60
  61 Il documento sullo stile del codice non dovrebbe essere letto come una legge
  62 assoluta che non può mai essere trasgredita.  Se c’è un a buona ragione
  63 (per esempio, una linea che diviene poco leggibile se divisa per rientrare
  64 nel limite di 80 colonne), fatelo e basta.
  65
  66 Notate che potete utilizzare lo strumento “clang-format” per aiutarvi con
  67 le regole, per una riformattazione automatica e veloce del vostro codice
  68 e per revisionare interi file per individuare errori nello stile di codifica,
  69 refusi e possibili miglioramenti.  Inoltre è utile anche per classificare gli
  70 ``#includes``, per allineare variabili/macro, per testi derivati ed altri
  71 compiti del genere.  Consultate il file
  72 :ref:`Documentation/translations/it_IT/process/clang-format.rst <clangformat>`
  73 per maggiori dettagli
  74
  75
  76 Livelli di astrazione
  77 *********************
  78
  79
  80 I professori di Informatica insegnano ai propri studenti a fare ampio uso dei
  81 livelli di astrazione nel nome della flessibilità e del nascondere informazioni.
  82 Certo il kernel fa un grande uso dell'astrazione; nessun progetto con milioni
  83 di righe di codice potrebbe fare altrimenti e sopravvivere.  Ma l'esperienza
  84 ha dimostrato che un'eccessiva o prematura astrazione può rivelarsi dannosa
  85 al pari di una prematura ottimizzazione.  L'astrazione dovrebbe essere usata
  86 fino al livello necessario e non oltre.
  87
  88 Ad un livello base, considerate una funzione che ha un argomento che viene
  89 sempre impostato a zero da tutti i chiamanti.  Uno potrebbe mantenere
  90 quell'argomento nell'eventualità qualcuno volesse sfruttare la flessibilità
  91 offerta.  In ogni caso, tuttavia, ci sono buone possibilità che il codice
  92 che va ad implementare questo argomento aggiuntivo, sia stato rotto in maniera
  93 sottile, in un modo che non è mai stato notato - perché non è mai stato usato.
  94 Oppure, quando sorge la necessità di avere più flessibilità, questo argomento
  95 non la fornisce in maniera soddisfacente.  Gli sviluppatori di Kernel,
  96 sottopongono costantemente patch che vanno a rimuovere gli argomenti
  97 inutilizzate; anche se, in generale, non avrebbero dovuto essere aggiunti.
  98
  99 I livelli di astrazione che nascondono l'accesso all'hardware -
 100 spesso per poter usare dei driver su diversi sistemi operativi - vengono
 101 particolarmente disapprovati.  Tali livelli oscurano il codice e possono
 102 peggiorare le prestazioni; essi non appartengono al kernel Linux.
 103
 104 D'altro canto, se vi ritrovate a dover copiare una quantità significativa di
 105 codice proveniente da un altro sottosistema del kernel, è tempo di chiedersi
 106 se, in effetti, non avrebbe più senso togliere parte di quel codice e metterlo
 107 in una libreria separata o di implementare quella funzionalità ad un livello
 108 più elevato.  Non c'è utilità nel replicare lo stesso codice per tutto
 109 il kernel.
 110
 111
 112 #ifdef e l'uso del preprocessore in generale
 113 ********************************************
 114
 115 Il preprocessore C sembra essere una fonte di attrazione per qualche
 116 programmatore C, che ci vede una via per ottenere una grande flessibilità
 117 all'interno di un file sorgente.  Ma il preprocessore non è scritto in C,
 118 e un suo massiccio impiego conduce a un codice che è molto più difficile
 119 da leggere per gli altri e che rende più difficile il lavoro di verifica del
 120 compilatore.  L'uso eccessivo del preprocessore è praticamente sempre il segno
 121 di un codice che necessita di un certo lavoro di pulizia.
 122
 123 La compilazione condizionata con #ifdef è, in effetti, un potente strumento,
 124 ed esso viene usato all'interno del kernel.  Ma esiste un piccolo desiderio:
 125 quello di vedere il codice coperto solo da una leggera spolverata di
 126 blocchi #ifdef.  Come regola generale, quando possibile, l'uso di #ifdef
 127 dovrebbe essere confinato nei file d'intestazione.  Il codice compilato
 128 condizionatamente può essere confinato a funzioni tali che, nel caso in cui
 129 il codice non deve essere presente, diventano vuote.  Il compilatore poi
 130 ottimizzerà la chiamata alla funzione vuota rimuovendola.  Il risultato è
 131 un codice molto più pulito, più facile da seguire.
 132
 133 Le macro del preprocessore C presentano una serie di pericoli, inclusi
 134 valutazioni multiple di espressioni che hanno effetti collaterali e non
 135 garantiscono una sicurezza rispetto ai tipi.  Se siete tentati dal definire
 136 una macro, considerate l'idea di creare invece una funzione inline.  Il codice
 137 che ne risulterà sarà lo stesso, ma le funzioni inline sono più leggibili,
 138 non considerano i propri argomenti più volte, e permettono al compilatore di
 139 effettuare controlli sul tipo degli argomenti e del valore di ritorno.
 140
 141
 142 Funzioni inline
 143 ***************
 144
 145 Comunque, anche le funzioni inline hanno i loro pericoli.  I programmatori
 146 potrebbero innamorarsi dell'efficienza percepita derivata dalla rimozione
 147 di una chiamata a funzione.  Queste funzioni, tuttavia, possono ridurre le
 148 prestazioni.  Dato che il loro codice viene replicato ovunque vi sia una
 149 chiamata ad esse, si finisce per gonfiare le dimensioni del kernel compilato.
 150 Questi, a turno, creano pressione sulla memoria cache del processore, e questo
 151 può causare rallentamenti importanti.  Le funzioni inline, di norma, dovrebbero
 152 essere piccole e usate raramente.  Il costo di una chiamata a funzione, dopo
 153 tutto, non è così alto; la creazione di molte funzioni inline è il classico
 154 esempio di un'ottimizzazione prematura.
 155
 156 In generale, i programmatori del kernel ignorano gli effetti della cache a
 157 loro rischio e pericolo.  Il classico compromesso tempo/spazio teorizzato
 158 all'inizio delle lezioni sulle strutture dati spesso non si applica
 159 all'hardware moderno.  Lo spazio *è* tempo, in questo senso un programma
 160 più grande sarà più lento rispetto ad uno più compatto.
 161
 162 I compilatori più recenti hanno preso un ruolo attivo nel decidere se
 163 una data funzione deve essere resa inline oppure no.  Quindi l'uso
 164 indiscriminato della parola chiave "inline" potrebbe non essere non solo
 165 eccessivo, ma anche irrilevante.
 166
 167 Sincronizzazione
 168 ****************
 169
 170 Nel maggio 2006, il sistema di rete "Devicescape" fu rilasciato in pompa magna
 171 sotto la licenza GPL e reso disponibile per la sua inclusione nella ramo
 172 principale del kernel.  Questa donazione fu una notizia bene accolta;
 173 il supporto per le reti senza fili era considerata, nel migliore dei casi,
 174 al di sotto degli standard; il sistema Deviscape offrì la promessa di una
 175 risoluzione a tale situazione.  Tuttavia, questo codice non fu inserito nel
 176 ramo principale fino al giugno del 2007 (2.6.22). Cosa accadde?
 177
 178 Quel codice mostrava numerosi segnali di uno sviluppo in azienda avvenuto
 179 a porte chiuse.  Ma in particolare, un grosso problema fu che non fu
 180 progettato per girare in un sistema multiprocessore.  Prima che questo
 181 sistema di rete (ora chiamato mac80211) potesse essere inserito, fu necessario
 182 un lavoro sugli schemi di sincronizzazione.
 183
 184 Una volta, il codice del kernel Linux poteva essere sviluppato senza pensare
 185 ai problemi di concorrenza presenti nei sistemi multiprocessore.  Ora,
 186 comunque, questo documento è stato scritto su di un portatile dual-core.
 187 Persino su sistemi a singolo processore, il lavoro svolto per incrementare
 188 la capacità di risposta aumenterà il livello di concorrenza interno al kernel.
 189 I giorni nei quali il codice poteva essere scritto senza pensare alla
 190 sincronizzazione sono da passati tempo.
 191
 192 Ogni risorsa (strutture dati, registri hardware, etc.) ai quali si potrebbe
 193 avere accesso simultaneo da più di un thread deve essere sincronizzato.  Il
 194 nuovo codice dovrebbe essere scritto avendo tale accortezza in testa;
 195 riadattare la sincronizzazione a posteriori è un compito molto più difficile.
 196 Gli sviluppatori del kernel dovrebbero prendersi il tempo di comprendere bene
 197 le primitive di sincronizzazione, in modo da sceglier lo strumento corretto
 198 per eseguire un compito.  Il codice che presenta una mancanza di attenzione
 199 alla concorrenza avrà un percorso difficile all'interno del ramo principale.
 200
 201 Regressioni
 202 ***********
 203
 204 Vale la pena menzionare un ultimo pericolo: potrebbe rivelarsi accattivante
 205 l'idea di eseguire un cambiamento (che potrebbe portare a grandi
 206 miglioramenti) che porterà ad alcune rotture per gli utenti esistenti.
 207 Questa tipologia di cambiamento è chiamata "regressione", e le regressioni son
 208 diventate mal viste nel ramo principale del kernel.  Con alcune eccezioni,
 209 i cambiamenti che causano regressioni saranno fermati se quest'ultime non
 210 potranno essere corrette in tempo utile.  È molto meglio quindi evitare
 211 la regressione fin dall'inizio.
 212
 213 Spesso si è argomentato che una regressione può essere giustificata se essa
 214 porta risolve più problemi di quanti non ne crei.  Perché, dunque, non fare
 215 un cambiamento se questo porta a nuove funzionalità a dieci sistemi per
 216 ognuno dei quali esso determina una rottura?  La migliore risposta a questa
 217 domanda ci è stata fornita da Linus nel luglio 2007:
 218
 219 ::
 220    Dunque, noi non sistemiamo bachi introducendo nuovi problemi. Quella
 221    via nasconde insidie, e nessuno può sapere del tutto se state facendo
 222    dei progressi reali. Sono due passi avanti e uno indietro, oppure
 223    un passo avanti e due indietro?
 224
 225 (http://lwn.net/Articles/243460/).
 226
 227 Una particolare tipologia di regressione mal vista consiste in una qualsiasi
 228 sorta di modifica all'ABI dello spazio utente.  Una volta che un'interfaccia
 229 viene esportata verso lo spazio utente, dev'essere supportata all'infinito.
 230 Questo fatto rende la creazione di interfacce per lo spazio utente
 231 particolarmente complicato: dato che non possono venir cambiate introducendo
 232 incompatibilità, esse devono essere fatte bene al primo colpo.  Per questa
 233 ragione sono sempre richieste: ampie riflessioni, documentazione chiara e
 234 ampie revisioni dell'interfaccia verso lo spazio utente.
 235
 236
 237 Strumenti di verifica del codice
 238 --------------------------------
 239 Almeno per ora la scrittura di codice priva di errori resta un ideale
 240 irraggiungibile ai più.  Quello che speriamo di poter fare, tuttavia, è
 241 trovare e correggere molti di questi errori prima che il codice entri nel
 242 ramo principale del kernel.  A tal scopo gli sviluppatori del kernel devono
 243 mettere insieme una schiera impressionante di strumenti che possano
 244 localizzare automaticamente un'ampia varietà di problemi.  Qualsiasi problema
 245 trovato dal computer è un problema che non affliggerà l'utente in seguito,
 246 ne consegue che gli strumenti automatici dovrebbero essere impiegati ovunque
 247 possibile.
 248
 249 Il primo passo consiste semplicemente nel fare attenzione agli avvertimenti
 250 proveniente dal compilatore.  Versioni moderne di gcc possono individuare
 251 (e segnalare) un gran numero di potenziali errori.  Molto spesso, questi
 252 avvertimenti indicano problemi reali.  Di regola, il codice inviato per la
 253 revisione non dovrebbe produrre nessun avvertimento da parte del compilatore.
 254 Per mettere a tacere gli avvertimenti, cercate di comprenderne le cause reali
 255 e cercate di evitare le "riparazioni" che fan sparire l'avvertimento senza
 256 però averne trovato la causa.
 257
 258 Tenete a mente che non tutti gli avvertimenti sono disabilitati di default.
 259 Costruite il kernel con "make EXTRA_CFLAGS=-W" per ottenerli tutti.
 260
 261 Il kernel fornisce differenti opzioni che abilitano funzionalità di debugging;
 262 molti di queste sono trovano all'interno del sotto menu "kernel hacking".
 263 La maggior parte di queste opzioni possono essere attivate per qualsiasi
 264 kernel utilizzato per lo sviluppo o a scopo di test.  In particolare dovreste
 265 attivare:
 266
 267  - ENABLE_WARN_DEPRECATED, ENABLE_MUST_CHECK, e FRAME_WARN per ottenere degli
 268    avvertimenti dedicati a problemi come l'uso di interfacce deprecate o
 269    l'ignorare un importante valore di ritorno di una funzione.  Il risultato
 270    generato da questi avvertimenti può risultare verboso, ma non bisogna
 271    preoccuparsi per gli avvertimenti provenienti da altre parti del kernel.
 272
 273  - DEBUG_OBJECTS aggiungerà un codice per tracciare il ciclo di vita di
 274    diversi oggetti creati dal kernel e avvisa quando qualcosa viene eseguito
 275    fuori controllo.  Se state aggiungendo un sottosistema che crea (ed
 276    esporta) oggetti complessi propri, considerate l'aggiunta di un supporto
 277    al debugging dell'oggetto.
 278
 279  - DEBUG_SLAB può trovare svariati errori di uso e di allocazione di memoria;
 280    esso dovrebbe esser usato dalla maggior parte dei kernel di sviluppo.
 281
 282  - DEBUG_SPINLOCK, DEBUG_ATOMIC_SLEEP, e DEBUG_MUTEXES troveranno un certo
 283    numero di errori comuni di sincronizzazione.
 284
 285 Esistono ancora delle altre opzioni di debugging, di alcune di esse
 286 discuteremo qui sotto.  Alcune di esse hanno un forte impatto e non dovrebbero
 287 essere usate tutte le volte.  Ma qualche volta il tempo speso nell'capire
 288 le opzioni disponibili porterà ad un risparmio di tempo nel breve termine.
 289
 290 Uno degli strumenti di debugging più tosti è il *locking checker*, o
 291 "lockdep".  Questo strumento traccerà qualsiasi acquisizione e rilascio di
 292 ogni *lock* (spinlock o mutex) nel sistema, l'ordine con il quale i *lock*
 293 sono acquisiti in relazione l'uno con l'altro, l'ambiente corrente di
 294 interruzione, eccetera.  Inoltre esso può assicurare che i *lock* vengano
 295 acquisiti sempre nello stesso ordine, che le stesse assunzioni sulle
 296 interruzioni si applichino in tutte le occasioni, e così via.  In altre parole,
 297 lockdep può scovare diversi scenari nei quali il sistema potrebbe, in rari
 298 casi, trovarsi in stallo.  Questa tipologia di problema può essere grave
 299 (sia per gli sviluppatori che per gli utenti) in un sistema in uso; lockdep
 300 permette di trovare tali problemi automaticamente e in anticipo.
 301
 302 In qualità di programmatore kernel diligente, senza dubbio, dovrete controllare
 303 il valore di ritorno di ogni operazione (come l'allocazione della memoria)
 304 poiché esso potrebbe fallire.  Il nocciolo della questione è che i percorsi
 305 di gestione degli errori, con grande probabilità, non sono mai stati
 306 collaudati del tutto.  Il codice collaudato tende ad essere codice bacato;
 307 potrete quindi essere più a vostro agio con il vostro codice se tutti questi
 308 percorsi fossero stati verificati un po' di volte.
 309
 310 Il kernel fornisce un framework per l'inserimento di fallimenti che fa
 311 esattamente al caso, specialmente dove sono coinvolte allocazioni di memoria.
 312 Con l'opzione per l'inserimento dei fallimenti abilitata, una certa percentuale
 313 di allocazione di memoria sarà destinata al fallimento; questi fallimenti
 314 possono essere ridotti ad uno specifico pezzo di codice.  Procedere con
 315 l'inserimento dei fallimenti attivo permette al programmatore di verificare
 316 come il codice risponde quando le cose vanno male.  Consultate:
 317 Documentation/fault-injection/fault-injection.txt per avere maggiori
 318 informazioni su come utilizzare questo strumento.
 319
 320 Altre tipologie di errori possono essere riscontrati con lo strumento di
 321 analisi statica "sparse".  Con Sparse, il programmatore può essere avvisato
 322 circa la confusione tra gli indirizzi dello spazio utente e dello spazio
 323 kernel, un miscuglio fra quantità big-endian e little-endian, il passaggio
 324 di un valore intero dove ci sia aspetta un gruppo di flag, e così via.
 325 Sparse deve essere installato separatamente (se il vostra distribuzione non
 326 lo prevede, potete trovarlo su https://sparse.wiki.kernel.org/index.php/Main_Page);
 327 può essere attivato sul codice aggiungendo "C=1" al comando make.
 328
 329 Lo strumento "Coccinelle" (http://coccinelle.lip6.fr/) è in grado di trovare
 330 una vasta varietà di potenziali problemi di codifica; e può inoltre proporre
 331 soluzioni per risolverli.  Un buon numero di "patch semantiche" per il kernel
 332 sono state preparate nella cartella scripts/coccinelle; utilizzando
 333 "make coccicheck" esso percorrerà tali patch semantiche e farà rapporto su
 334 qualsiasi problema trovato.  Per maggiori informazioni, consultate
 335 :ref:`Documentation/dev-tools/coccinelle.rst <devtools_coccinelle>`.
 336
 337 Altri errori di portabilità sono meglio scovati compilando il vostro codice
 338 per altre architetture.  Se non vi accade di avere un sistema S/390 o una
 339 scheda di sviluppo Blackfin sotto mano, potete comunque continuare la fase
 340 di compilazione.  Un vasto numero di cross-compilatori per x86 possono
 341 essere trovati al sito:
 342
 343         http://www.kernel.org/pub/tools/crosstool/
 344
 345 Il tempo impiegato nell'installare e usare questi compilatori sarà d'aiuto
 346 nell'evitare situazioni imbarazzanti nel futuro.
 347
 348
 349 Documentazione
 350 --------------
 351
 352 La documentazione è spesso stata più un'eccezione che una regola nello
 353 sviluppo del kernel.  Nonostante questo, un'adeguata documentazione aiuterà
 354 a facilitare l'inserimento di nuovo codice nel kernel, rende la vita più
 355 facile per gli altri sviluppatori e sarà utile per i vostri utenti.  In molti
 356 casi, la documentazione è divenuta sostanzialmente obbligatoria.
 357
 358 La prima parte di documentazione per qualsiasi patch è il suo changelog.
 359 Questi dovrebbero descrivere le problematiche risolte, la tipologia di
 360 soluzione, le persone che lavorano alla patch, ogni effetto rilevante
 361 sulle prestazioni e tutto ciò che può servire per la comprensione della
 362 patch.  Assicuratevi che il changelog dica *perché*, vale la pena aggiungere
 363 la patch; un numero sorprendente di sviluppatori sbaglia nel fornire tale
 364 informazione.
 365
 366 Qualsiasi codice che aggiunge una nuova interfaccia in spazio utente - inclusi
 367 nuovi file in sysfs o /proc - dovrebbe includere la documentazione di tale
 368 interfaccia così da permette agli sviluppatori dello spazio utente di sapere
 369 con cosa stanno lavorando.  Consultate: Documentation/ABI/README per avere una
 370 descrizione di come questi documenti devono essere impostati e quali
 371 informazioni devono essere fornite.
 372
 373 Il file :ref:`Documentation/translations/it_IT/admin-guide/kernel-parameters.rst <kernelparameters>`
 374 descrive tutti i parametri di avvio del kernel.  Ogni patch che aggiunga
 375 nuovi parametri dovrebbe aggiungere nuove voci a questo file.
 376
 377 Ogni nuova configurazione deve essere accompagnata da un testo di supporto
 378 che spieghi chiaramente le opzioni e spieghi quando l'utente potrebbe volerle
 379 selezionare.
 380
 381 Per molti sottosistemi le informazioni sull'API interna sono documentate sotto
 382 forma di commenti formattati in maniera particolare; questi commenti possono
 383 essere estratti e formattati in differenti modi attraverso lo script
 384 "kernel-doc".  Se state lavorando all'interno di un sottosistema che ha
 385 commenti kerneldoc dovreste mantenerli e aggiungerli, in maniera appropriata,
 386 per le funzioni disponibili esternamente.  Anche in aree che non sono molto
 387 documentate, non c'è motivo per non aggiungere commenti kerneldoc per il
 388 futuro; infatti, questa può essere un'attività utile per sviluppatori novizi
 389 del kernel.  Il formato di questi commenti, assieme alle informazione su come
 390 creare modelli per kerneldoc, possono essere trovati in
 391 :ref:`Documentation/translations/it_IT/doc-guide/ <doc_guide>`.
 392
 393 Chiunque legga un ammontare significativo di codice kernel noterà che, spesso,
 394 i commenti si fanno maggiormente notare per la loro assenza.  Ancora una volta,
 395 le aspettative verso il nuovo codice sono più alte rispetto al passato;
 396 inserire codice privo di commenti sarà più difficile.  Detto ciò, va aggiunto
 397 che non si desiderano commenti prolissi per il codice.  Il codice dovrebbe
 398 essere, di per sé, leggibile, con dei commenti che spieghino gli aspetti più
 399 sottili.
 400
 401 Determinate cose dovrebbero essere sempre commentate.  L'uso di barriere
 402 di memoria dovrebbero essere accompagnate da una riga che spieghi perché sia
 403 necessaria.  Le regole di sincronizzazione per le strutture dati, generalmente,
 404 necessitano di una spiegazioni da qualche parte.  Le strutture dati più
 405 importanti, in generale, hanno bisogno di una documentazione onnicomprensiva.
 406 Le dipendenze che non sono ovvie tra bit separati di codice dovrebbero essere
 407 indicate.  Tutto ciò che potrebbe indurre un inserviente del codice a fare
 408 una "pulizia" incorretta, ha bisogno di un commento che dica perché è stato
 409 fatto in quel modo.  E così via.
 410
 411 Cambiamenti interni dell'API
 412 ----------------------------
 413
 414 L'interfaccia binaria fornita dal kernel allo spazio utente non può essere
 415 rotta tranne che in circostanze eccezionali.  L'interfaccia di programmazione
 416 interna al kernel, invece, è estremamente fluida e può essere modificata al
 417 bisogno.  Se vi trovate a dover lavorare attorno ad un'API del kernel o
 418 semplicemente non state utilizzando una funzionalità offerta perché questa
 419 non rispecchia i vostri bisogni, allora questo potrebbe essere un segno che
 420 l'API ha bisogno di essere cambiata.  In qualità di sviluppatore del kernel,
 421 hai il potere di fare questo tipo di modifica.
 422
 423 Ci sono ovviamente alcuni punti da cogliere.  I cambiamenti API possono essere
 424 fatti, ma devono essere giustificati.  Quindi ogni patch che porta ad una
 425 modifica dell'API interna dovrebbe essere accompagnata da una descrizione
 426 della modifica in sé e del perché essa è necessaria.  Questo tipo di
 427 cambiamenti dovrebbero, inoltre, essere fatti in una patch separata, invece di
 428 essere sepolti all'interno di una patch più grande.
 429
 430 L'altro punto da cogliere consiste nel fatto che uno sviluppatore che
 431 modifica l'API deve, in generale, essere responsabile della correzione
 432 di tutto il codice del kernel che viene rotto per via della sua modifica.
 433 Per una funzione ampiamente usata, questo compito può condurre letteralmente
 434 a centinaia o migliaia di modifiche, molte delle quali sono in conflitto con
 435 il lavoro svolto da altri sviluppatori.  Non c'è bisogno di dire che questo
 436 può essere un lavoro molto grosso, quindi è meglio essere sicuri che la
 437 motivazione sia ben solida.  Notate che lo strumento Coccinelle può fornire
 438 un aiuto con modifiche estese dell'API.
 439
 440 Quando viene fatta una modifica API incompatibile, una persona dovrebbe,
 441 quando possibile, assicurarsi che quel codice non aggiornato sia trovato
 442 dal compilatore.  Questo vi aiuterà ad essere sicuri d'avere trovato,
 443 tutti gli usi di quell'interfaccia.  Inoltre questo avviserà gli sviluppatori
 444 di codice fuori dal kernel che c'è un cambiamento per il quale è necessario del
 445 lavoro.  Il supporto al codice fuori dal kernel non è qualcosa di cui gli
 446 sviluppatori del kernel devono preoccuparsi, ma non dobbiamo nemmeno rendere
 447 più difficile del necessario la vita agli sviluppatori di questo codice.