0001 .. include:: ../disclaimer-ita.rst
0002
0003 :Original: :ref:`Documentation/process/clang-format.rst <clangformat>`
0004 :Translator: Federico Vaga <federico.vaga@vaga.pv.it>
0005
0006 .. _it_clangformat:
0007
0008 clang-format
0009 ============
0010 ``clang-format`` è uno strumento per formattare codice C/C++/... secondo
0011 un gruppo di regole ed euristiche. Come tutti gli strumenti, non è perfetto
0012 e non copre tutti i singoli casi, ma è abbastanza buono per essere utile.
0013
0014 ``clang-format`` può essere usato per diversi fini:
0015
0016 - Per riformattare rapidamente un blocco di codice secondo lo stile del
0017 kernel. Particolarmente utile quando si sposta del codice e lo si
0018 allinea/ordina. Vedere it_clangformatreformat_.
0019
0020 - Identificare errori di stile, refusi e possibili miglioramenti nei
0021 file che mantieni, le modifiche che revisioni, le differenze,
0022 eccetera. Vedere it_clangformatreview_.
0023
0024 - Ti aiuta a seguire lo stile del codice, particolarmente utile per i
0025 nuovi arrivati o per coloro che lavorano allo stesso tempo su diversi
0026 progetti con stili di codifica differenti.
0027
0028 Il suo file di configurazione è ``.clang-format`` e si trova nella cartella
0029 principale dei sorgenti del kernel. Le regole scritte in quel file tentano
0030 di approssimare le lo stile di codifica del kernel. Si tenta anche di seguire
0031 il più possibile
0032 :ref:`Documentation/translations/it_IT/process/coding-style.rst <it_codingstyle>`.
0033 Dato che non tutto il kernel segue lo stesso stile, potreste voler aggiustare
0034 le regole di base per un particolare sottosistema o cartella. Per farlo,
0035 potete sovrascriverle scrivendole in un altro file ``.clang-format`` in
0036 una sottocartella.
0037
0038 Questo strumento è già stato incluso da molto tempo nelle distribuzioni
0039 Linux più popolari. Cercate ``clang-format`` nel vostro repositorio.
0040 Altrimenti, potete scaricare una versione pre-generata dei binari di LLVM/clang
0041 oppure generarlo dai codici sorgenti:
0042
0043 http://releases.llvm.org/download.html
0044
0045 Troverete più informazioni ai seguenti indirizzi:
0046
0047 https://clang.llvm.org/docs/ClangFormat.html
0048
0049 https://clang.llvm.org/docs/ClangFormatStyleOptions.html
0050
0051
0052 .. _it_clangformatreview:
0053
0054 Revisionare lo stile di codifica per file e modifiche
0055 -----------------------------------------------------
0056
0057 Eseguendo questo programma, potrete revisionare un intero sottosistema,
0058 cartella o singoli file alla ricerca di errori di stile, refusi o
0059 miglioramenti.
0060
0061 Per farlo, potete eseguire qualcosa del genere::
0062
0063 # Make sure your working directory is clean!
0064 clang-format -i kernel/*.[ch]
0065
0066 E poi date un'occhiata a *git diff*.
0067
0068 Osservare le righe di questo diff è utile a migliorare/aggiustare
0069 le opzioni di stile nel file di configurazione; così come per verificare
0070 le nuove funzionalità/versioni di ``clang-format``.
0071
0072 ``clang-format`` è in grado di leggere diversi diff unificati, quindi
0073 potrete revisionare facilmente delle modifiche e *git diff*.
0074 La documentazione si trova al seguente indirizzo:
0075
0076 https://clang.llvm.org/docs/ClangFormat.html#script-for-patch-reformatting
0077
0078 Per evitare che ``clang-format`` formatti alcune parti di un file, potete
0079 scrivere nel codice::
0080
0081 int formatted_code;
0082 // clang-format off
0083 void unformatted_code ;
0084 // clang-format on
0085 void formatted_code_again;
0086
0087 Nonostante si attraente l'idea di utilizzarlo per mantenere un file
0088 sempre in sintonia con ``clang-format``, specialmente per file nuovi o
0089 se siete un manutentore, ricordatevi che altre persone potrebbero usare
0090 una versione diversa di ``clang-format`` oppure non utilizzarlo del tutto.
0091 Quindi, dovreste trattenervi dall'usare questi marcatori nel codice del
0092 kernel; almeno finché non vediamo che ``clang-format`` è diventato largamente
0093 utilizzato.
0094
0095
0096 .. _it_clangformatreformat:
0097
0098 Riformattare blocchi di codice
0099 ------------------------------
0100
0101 Utilizzando dei plugin per il vostro editor, potete riformattare una
0102 blocco (selezione) di codice con una singola combinazione di tasti.
0103 Questo è particolarmente utile: quando si riorganizza il codice, per codice
0104 complesso, macro multi-riga (e allineare le loro "barre"), eccetera.
0105
0106 Ricordatevi che potete sempre aggiustare le modifiche in quei casi dove
0107 questo strumento non ha fatto un buon lavoro. Ma come prima approssimazione,
0108 può essere davvero molto utile.
0109
0110 Questo programma si integra con molti dei più popolari editor. Alcuni di
0111 essi come vim, emacs, BBEdit, Visaul Studio, lo supportano direttamente.
0112 Al seguente indirizzo troverete le istruzioni:
0113
0114 https://clang.llvm.org/docs/ClangFormat.html
0115
0116 Per Atom, Eclipse, Sublime Text, Visual Studio Code, XCode e altri editor
0117 e IDEs dovreste essere in grado di trovare dei plugin pronti all'uso.
0118
0119 Per questo caso d'uso, considerate l'uso di un secondo ``.clang-format``
0120 che potete personalizzare con le vostre opzioni.
0121 Consultare it_clangformatextra_.
0122
0123
0124 .. _it_clangformatmissing:
0125
0126 Cose non supportate
0127 -------------------
0128
0129 ``clang-format`` non ha il supporto per alcune cose che sono comuni nel
0130 codice del kernel. Sono facili da ricordare; quindi, se lo usate
0131 regolarmente, imparerete rapidamente a evitare/ignorare certi problemi.
0132
0133 In particolare, quelli più comuni che noterete sono:
0134
0135 - Allineamento di ``#define`` su una singola riga, per esempio::
0136
0137 #define TRACING_MAP_BITS_DEFAULT 11
0138 #define TRACING_MAP_BITS_MAX 17
0139 #define TRACING_MAP_BITS_MIN 7
0140
0141 contro::
0142
0143 #define TRACING_MAP_BITS_DEFAULT 11
0144 #define TRACING_MAP_BITS_MAX 17
0145 #define TRACING_MAP_BITS_MIN 7
0146
0147 - Allineamento dei valori iniziali, per esempio::
0148
0149 static const struct file_operations uprobe_events_ops = {
0150 .owner = THIS_MODULE,
0151 .open = probes_open,
0152 .read = seq_read,
0153 .llseek = seq_lseek,
0154 .release = seq_release,
0155 .write = probes_write,
0156 };
0157
0158 contro::
0159
0160 static const struct file_operations uprobe_events_ops = {
0161 .owner = THIS_MODULE,
0162 .open = probes_open,
0163 .read = seq_read,
0164 .llseek = seq_lseek,
0165 .release = seq_release,
0166 .write = probes_write,
0167 };
0168
0169
0170 .. _it_clangformatextra:
0171
0172 Funzionalità e opzioni aggiuntive
0173 ---------------------------------
0174
0175 Al fine di minimizzare le differenze fra il codice attuale e l'output
0176 del programma, alcune opzioni di stile e funzionalità non sono abilitate
0177 nella configurazione base. In altre parole, lo scopo è di rendere le
0178 differenze le più piccole possibili, permettendo la semplificazione
0179 della revisione di file, differenze e modifiche.
0180
0181 In altri casi (per esempio un particolare sottosistema/cartella/file), lo
0182 stile del kernel potrebbe essere diverso e abilitare alcune di queste
0183 opzioni potrebbe dare risultati migliori.
0184
0185 Per esempio:
0186
0187 - Allineare assegnamenti (``AlignConsecutiveAssignments``).
0188
0189 - Allineare dichiarazioni (``AlignConsecutiveDeclarations``).
0190
0191 - Riorganizzare il testo nei commenti (``ReflowComments``).
0192
0193 - Ordinare gli ``#include`` (``SortIncludes``).
0194
0195 Piuttosto che per interi file, solitamente sono utili per la riformattazione
0196 di singoli blocchi. In alternativa, potete creare un altro file
0197 ``.clang-format`` da utilizzare con il vostro editor/IDE.
