Documentation/translations/it_IT/process/clang-format.rst

   1 .. include:: ../disclaimer-ita.rst
   2
   3 :Original: :ref:`Documentation/process/clang-format.rst <clangformat>`
   4 :Translator: Federico Vaga <federico.vaga@vaga.pv.it>
   5
   6 .. _it_clangformat:
   7
   8 clang-format
   9 ============
  10 ``clang-format`` è uno strumento per formattare codice C/C++/... secondo
  11 un gruppo di regole ed euristiche. Come tutti gli strumenti, non è perfetto
  12 e non copre tutti i singoli casi, ma è abbastanza buono per essere utile.
  13
  14 ``clang-format`` può essere usato per diversi fini:
  15
  16   - Per riformattare rapidamente un blocco di codice secondo lo stile del
  17     kernel. Particolarmente utile quando si sposta del codice e lo si
  18     allinea/ordina. Vedere it_clangformatreformat_.
  19
  20   - Identificare errori di stile, refusi e possibili miglioramenti nei
  21     file che mantieni, le modifiche che revisioni, le differenze,
  22     eccetera. Vedere it_clangformatreview_.
  23
  24   - Ti aiuta a seguire lo stile del codice, particolarmente utile per i
  25     nuovi arrivati o per coloro che lavorano allo stesso tempo su diversi
  26     progetti con stili di codifica differenti.
  27
  28 Il suo file di configurazione è ``.clang-format`` e si trova nella cartella
  29 principale dei sorgenti del kernel. Le regole scritte in quel file tentano
  30 di approssimare le lo stile di codifica del kernel. Si tenta anche di seguire
  31 il più possibile
  32 :ref:`Documentation/translations/it_IT/process/coding-style.rst <it_codingstyle>`.
  33 Dato che non tutto il kernel segue lo stesso stile, potreste voler aggiustare
  34 le regole di base per un particolare sottosistema o cartella. Per farlo,
  35 potete sovrascriverle scrivendole in un altro file ``.clang-format`` in
  36 una sottocartella.
  37
  38 Questo strumento è già stato incluso da molto tempo nelle distribuzioni
  39 Linux più popolari. Cercate ``clang-format`` nel vostro repositorio.
  40 Altrimenti, potete scaricare una versione pre-generata dei binari di LLVM/clang
  41 oppure generarlo dai codici sorgenti:
  42
  43     http://releases.llvm.org/download.html
  44
  45 Troverete più informazioni ai seguenti indirizzi:
  46
  47     https://clang.llvm.org/docs/ClangFormat.html
  48
  49     https://clang.llvm.org/docs/ClangFormatStyleOptions.html
  50
  51
  52 .. _it_clangformatreview:
  53
  54 Revisionare lo stile di codifica per file e modifiche
  55 -----------------------------------------------------
  56
  57 Eseguendo questo programma, potrete revisionare un intero sottosistema,
  58 cartella o singoli file alla ricerca di errori di stile, refusi o
  59 miglioramenti.
  60
  61 Per farlo, potete eseguire qualcosa del genere::
  62
  63     # Make sure your working directory is clean!
  64     clang-format -i kernel/*.[ch]
  65
  66 E poi date un'occhiata a *git diff*.
  67
  68 Osservare le righe di questo diff è utile a migliorare/aggiustare
  69 le opzioni di stile nel file di configurazione; così come per verificare
  70 le nuove funzionalità/versioni di ``clang-format``.
  71
  72 ``clang-format`` è in grado di leggere diversi diff unificati, quindi
  73 potrete revisionare facilmente delle modifiche e *git diff*.
  74 La documentazione si trova al seguente indirizzo:
  75
  76     https://clang.llvm.org/docs/ClangFormat.html#script-for-patch-reformatting
  77
  78 Per evitare che ``clang-format`` formatti alcune parti di un file, potete
  79 scrivere nel codice::
  80
  81     int formatted_code;
  82     // clang-format off
  83         void    unformatted_code  ;
  84     // clang-format on
  85     void formatted_code_again;
  86
  87 Nonostante si attraente l'idea di utilizzarlo per mantenere un file
  88 sempre in sintonia con ``clang-format``, specialmente per file nuovi o
  89 se siete un manutentore, ricordatevi che altre persone potrebbero usare
  90 una versione diversa di ``clang-format`` oppure non utilizzarlo del tutto.
  91 Quindi, dovreste trattenervi dall'usare questi marcatori nel codice del
  92 kernel; almeno finché non vediamo che ``clang-format`` è diventato largamente
  93 utilizzato.
  94
  95
  96 .. _it_clangformatreformat:
  97
  98 Riformattare blocchi di codice
  99 ------------------------------
 100
 101 Utilizzando dei plugin per il vostro editor, potete riformattare una
 102 blocco (selezione) di codice con una singola combinazione di tasti.
 103 Questo è particolarmente utile: quando si riorganizza il codice, per codice
 104 complesso, macro multi-riga (e allineare le loro "barre"), eccetera.
 105
 106 Ricordatevi che potete sempre aggiustare le modifiche in quei casi dove
 107 questo strumento non ha fatto un buon lavoro. Ma come prima approssimazione,
 108 può essere davvero molto utile.
 109
 110 Questo programma si integra con molti dei più popolari editor. Alcuni di
 111 essi come vim, emacs, BBEdit, Visaul Studio, lo supportano direttamente.
 112 Al seguente indirizzo troverete le istruzioni:
 113
 114     https://clang.llvm.org/docs/ClangFormat.html
 115
 116 Per Atom, Eclipse, Sublime Text, Visual Studio Code, XCode e altri editor
 117 e IDEs dovreste essere in grado di trovare dei plugin pronti all'uso.
 118
 119 Per questo caso d'uso, considerate l'uso di un secondo ``.clang-format``
 120 che potete personalizzare con le vostre opzioni.
 121 Consultare it_clangformatextra_.
 122
 123
 124 .. _it_clangformatmissing:
 125
 126 Cose non supportate
 127 -------------------
 128
 129 ``clang-format`` non ha il supporto per alcune cose che sono comuni nel
 130 codice del kernel. Sono facili da ricordare; quindi, se lo usate
 131 regolarmente, imparerete rapidamente a evitare/ignorare certi problemi.
 132
 133 In particolare, quelli più comuni che noterete sono:
 134
 135   - Allineamento di ``#define`` su una singola riga, per esempio::
 136
 137         #define TRACING_MAP_BITS_DEFAULT       11
 138         #define TRACING_MAP_BITS_MAX           17
 139         #define TRACING_MAP_BITS_MIN           7
 140
 141     contro::
 142
 143         #define TRACING_MAP_BITS_DEFAULT 11
 144         #define TRACING_MAP_BITS_MAX 17
 145         #define TRACING_MAP_BITS_MIN 7
 146
 147   - Allineamento dei valori iniziali, per esempio::
 148
 149         static const struct file_operations uprobe_events_ops = {
 150                 .owner          = THIS_MODULE,
 151                 .open           = probes_open,
 152                 .read           = seq_read,
 153                 .llseek         = seq_lseek,
 154                 .release        = seq_release,
 155                 .write          = probes_write,
 156         };
 157
 158     contro::
 159
 160         static const struct file_operations uprobe_events_ops = {
 161                 .owner = THIS_MODULE,
 162                 .open = probes_open,
 163                 .read = seq_read,
 164                 .llseek = seq_lseek,
 165                 .release = seq_release,
 166                 .write = probes_write,
 167         };
 168
 169
 170 .. _it_clangformatextra:
 171
 172 Funzionalità e opzioni aggiuntive
 173 ---------------------------------
 174
 175 Al fine di minimizzare le differenze fra il codice attuale e l'output
 176 del programma, alcune opzioni di stile e funzionalità non sono abilitate
 177 nella configurazione base. In altre parole, lo scopo è di rendere le
 178 differenze le più piccole possibili, permettendo la semplificazione
 179 della revisione di file, differenze e modifiche.
 180
 181 In altri casi (per esempio un particolare sottosistema/cartella/file), lo
 182 stile del kernel potrebbe essere diverso e abilitare alcune di queste
 183 opzioni potrebbe dare risultati migliori.
 184
 185 Per esempio:
 186
 187   - Allineare assegnamenti (``AlignConsecutiveAssignments``).
 188
 189   - Allineare dichiarazioni (``AlignConsecutiveDeclarations``).
 190
 191   - Riorganizzare il testo nei commenti (``ReflowComments``).
 192
 193   - Ordinare gli ``#include`` (``SortIncludes``).
 194
 195 Piuttosto che per interi file, solitamente sono utili per la riformattazione
 196 di singoli blocchi. In alternativa, potete creare un altro file
 197 ``.clang-format`` da utilizzare con il vostro editor/IDE.