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    https://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.
198