clang-format.rst (7311B)
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 8clang-format 9============ 10``clang-format`` è uno strumento per formattare codice C/C++/... secondo 11un gruppo di regole ed euristiche. Come tutti gli strumenti, non è perfetto 12e 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 28Il suo file di configurazione è ``.clang-format`` e si trova nella cartella 29principale dei sorgenti del kernel. Le regole scritte in quel file tentano 30di approssimare le lo stile di codifica del kernel. Si tenta anche di seguire 31il più possibile 32:ref:`Documentation/translations/it_IT/process/coding-style.rst <it_codingstyle>`. 33Dato che non tutto il kernel segue lo stesso stile, potreste voler aggiustare 34le regole di base per un particolare sottosistema o cartella. Per farlo, 35potete sovrascriverle scrivendole in un altro file ``.clang-format`` in 36una sottocartella. 37 38Questo strumento è già stato incluso da molto tempo nelle distribuzioni 39Linux più popolari. Cercate ``clang-format`` nel vostro repositorio. 40Altrimenti, potete scaricare una versione pre-generata dei binari di LLVM/clang 41oppure generarlo dai codici sorgenti: 42 43 http://releases.llvm.org/download.html 44 45Troverete 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 54Revisionare lo stile di codifica per file e modifiche 55----------------------------------------------------- 56 57Eseguendo questo programma, potrete revisionare un intero sottosistema, 58cartella o singoli file alla ricerca di errori di stile, refusi o 59miglioramenti. 60 61Per farlo, potete eseguire qualcosa del genere:: 62 63 # Make sure your working directory is clean! 64 clang-format -i kernel/*.[ch] 65 66E poi date un'occhiata a *git diff*. 67 68Osservare le righe di questo diff è utile a migliorare/aggiustare 69le opzioni di stile nel file di configurazione; così come per verificare 70le nuove funzionalità/versioni di ``clang-format``. 71 72``clang-format`` è in grado di leggere diversi diff unificati, quindi 73potrete revisionare facilmente delle modifiche e *git diff*. 74La documentazione si trova al seguente indirizzo: 75 76 https://clang.llvm.org/docs/ClangFormat.html#script-for-patch-reformatting 77 78Per evitare che ``clang-format`` formatti alcune parti di un file, potete 79scrivere 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 87Nonostante si attraente l'idea di utilizzarlo per mantenere un file 88sempre in sintonia con ``clang-format``, specialmente per file nuovi o 89se siete un manutentore, ricordatevi che altre persone potrebbero usare 90una versione diversa di ``clang-format`` oppure non utilizzarlo del tutto. 91Quindi, dovreste trattenervi dall'usare questi marcatori nel codice del 92kernel; almeno finché non vediamo che ``clang-format`` è diventato largamente 93utilizzato. 94 95 96.. _it_clangformatreformat: 97 98Riformattare blocchi di codice 99------------------------------ 100 101Utilizzando dei plugin per il vostro editor, potete riformattare una 102blocco (selezione) di codice con una singola combinazione di tasti. 103Questo è particolarmente utile: quando si riorganizza il codice, per codice 104complesso, macro multi-riga (e allineare le loro "barre"), eccetera. 105 106Ricordatevi che potete sempre aggiustare le modifiche in quei casi dove 107questo strumento non ha fatto un buon lavoro. Ma come prima approssimazione, 108può essere davvero molto utile. 109 110Questo programma si integra con molti dei più popolari editor. Alcuni di 111essi come vim, emacs, BBEdit, Visaul Studio, lo supportano direttamente. 112Al seguente indirizzo troverete le istruzioni: 113 114 https://clang.llvm.org/docs/ClangFormat.html 115 116Per Atom, Eclipse, Sublime Text, Visual Studio Code, XCode e altri editor 117e IDEs dovreste essere in grado di trovare dei plugin pronti all'uso. 118 119Per questo caso d'uso, considerate l'uso di un secondo ``.clang-format`` 120che potete personalizzare con le vostre opzioni. 121Consultare it_clangformatextra_. 122 123 124.. _it_clangformatmissing: 125 126Cose non supportate 127------------------- 128 129``clang-format`` non ha il supporto per alcune cose che sono comuni nel 130codice del kernel. Sono facili da ricordare; quindi, se lo usate 131regolarmente, imparerete rapidamente a evitare/ignorare certi problemi. 132 133In 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 172Funzionalità e opzioni aggiuntive 173--------------------------------- 174 175Al fine di minimizzare le differenze fra il codice attuale e l'output 176del programma, alcune opzioni di stile e funzionalità non sono abilitate 177nella configurazione base. In altre parole, lo scopo è di rendere le 178differenze le più piccole possibili, permettendo la semplificazione 179della revisione di file, differenze e modifiche. 180 181In altri casi (per esempio un particolare sottosistema/cartella/file), lo 182stile del kernel potrebbe essere diverso e abilitare alcune di queste 183opzioni potrebbe dare risultati migliori. 184 185Per 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 195Piuttosto che per interi file, solitamente sono utili per la riformattazione 196di singoli blocchi. In alternativa, potete creare un altro file 197``.clang-format`` da utilizzare con il vostro editor/IDE.