]>
Commit | Line | Data |
---|---|---|
edba5eec FV |
1 | .. include:: ../disclaimer-ita.rst |
2 | ||
3 | :Original: :ref:`Documentation/process/coding-style.rst <codingstyle>` | |
4 | :Translator: Federico Vaga <federico.vaga@vaga.pv.it> | |
5 | ||
6 | .. _it_codingstyle: | |
7 | ||
8 | Stile del codice per il kernel Linux | |
9 | ==================================== | |
10 | ||
11 | Questo è un breve documento che descrive lo stile di codice preferito per | |
12 | il kernel Linux. Lo stile di codifica è molto personale e non voglio | |
13 | **forzare** nessuno ad accettare il mio, ma questo stile è quello che | |
14 | dev'essere usato per qualsiasi cosa che io sia in grado di mantenere, e l'ho | |
15 | preferito anche per molte altre cose. Per favore, almeno tenete in | |
16 | considerazione le osservazioni espresse qui. | |
17 | ||
18 | La prima cosa che suggerisco è quella di stamparsi una copia degli standard | |
19 | di codifica GNU e di NON leggerla. Bruciatela, è un grande gesto simbolico. | |
20 | ||
21 | Comunque, ecco i punti: | |
22 | ||
23 | 1) Indentazione | |
24 | --------------- | |
25 | ||
26 | La tabulazione (tab) è di 8 caratteri e così anche le indentazioni. Ci sono | |
27 | alcuni movimenti di eretici che vorrebbero l'indentazione a 4 (o perfino 2!) | |
28 | caratteri di profondità, che è simile al tentativo di definire il valore del | |
29 | pi-greco a 3. | |
30 | ||
31 | Motivazione: l'idea dell'indentazione è di definire chiaramente dove un blocco | |
32 | di controllo inizia e finisce. Specialmente quando siete rimasti a guardare lo | |
33 | schermo per 20 ore a file, troverete molto più facile capire i livelli di | |
34 | indentazione se questi sono larghi. | |
35 | ||
36 | Ora, alcuni rivendicano che un'indentazione da 8 caratteri sposta il codice | |
37 | troppo a destra e che quindi rende difficile la lettura su schermi a 80 | |
38 | caratteri. La risposta a questa affermazione è che se vi servono più di 3 | |
39 | livelli di indentazione, siete comunque fregati e dovreste correggere il vostro | |
40 | programma. | |
41 | ||
42 | In breve, l'indentazione ad 8 caratteri rende più facile la lettura, e in | |
43 | aggiunta vi avvisa quando state annidando troppo le vostre funzioni. | |
44 | Tenete ben a mente questo avviso. | |
45 | ||
46 | Al fine di facilitare l'indentazione del costrutto switch, si preferisce | |
47 | allineare sulla stessa colonna la parola chiave ``switch`` e i suoi | |
48 | subordinati ``case``. In questo modo si evita una doppia indentazione per | |
49 | i ``case``. Un esempio.: | |
50 | ||
51 | .. code-block:: c | |
52 | ||
53 | switch (suffix) { | |
54 | case 'G': | |
55 | case 'g': | |
56 | mem <<= 30; | |
57 | break; | |
58 | case 'M': | |
59 | case 'm': | |
60 | mem <<= 20; | |
61 | break; | |
62 | case 'K': | |
63 | case 'k': | |
64 | mem <<= 10; | |
65 | /* fall through */ | |
66 | default: | |
67 | break; | |
68 | } | |
69 | ||
70 | A meno che non vogliate nascondere qualcosa, non mettete più istruzioni sulla | |
71 | stessa riga: | |
72 | ||
73 | .. code-block:: c | |
74 | ||
75 | if (condition) do_this; | |
76 | do_something_everytime; | |
77 | ||
78 | né mettete più assegnamenti sulla stessa riga. Lo stile del kernel | |
79 | è ultrasemplice. Evitate espressioni intricate. | |
80 | ||
81 | Al di fuori dei commenti, della documentazione ed escludendo i Kconfig, gli | |
82 | spazi non vengono mai usati per l'indentazione, e l'esempio qui sopra è | |
83 | volutamente errato. | |
84 | ||
85 | Procuratevi un buon editor di testo e non lasciate spazi bianchi alla fine | |
86 | delle righe. | |
87 | ||
88 | ||
89 | 2) Spezzare righe lunghe e stringhe | |
90 | ----------------------------------- | |
91 | ||
92 | Lo stile del codice riguarda la leggibilità e la manutenibilità utilizzando | |
93 | strumenti comuni. | |
94 | ||
95 | Il limite delle righe è di 80 colonne e questo e un limite fortemente | |
96 | desiderato. | |
97 | ||
98 | Espressioni più lunghe di 80 colonne saranno spezzettate in pezzi più piccoli, | |
99 | a meno che eccedere le 80 colonne non aiuti ad aumentare la leggibilità senza | |
100 | nascondere informazioni. I pezzi derivati sono sostanzialmente più corti degli | |
101 | originali e vengono posizionati più a destra. Lo stesso si applica, nei file | |
102 | d'intestazione, alle funzioni con una lista di argomenti molto lunga. Tuttavia, | |
103 | non spezzettate mai le stringhe visibili agli utenti come i messaggi di | |
104 | printk, questo perché inibireste la possibilità d'utilizzare grep per cercarle. | |
105 | ||
106 | 3) Posizionamento di parentesi graffe e spazi | |
107 | --------------------------------------------- | |
108 | ||
109 | Un altro problema che s'affronta sempre quando si parla di stile in C è | |
110 | il posizionamento delle parentesi graffe. Al contrario della dimensione | |
111 | dell'indentazione, non ci sono motivi tecnici sulla base dei quali scegliere | |
112 | una strategia di posizionamento o un'altra; ma il modo qui preferito, | |
113 | come mostratoci dai profeti Kernighan e Ritchie, è quello di | |
114 | posizionare la parentesi graffa di apertura per ultima sulla riga, e quella | |
115 | di chiusura per prima su una nuova riga, così: | |
116 | ||
117 | .. code-block:: c | |
118 | ||
119 | if (x is true) { | |
120 | we do y | |
121 | } | |
122 | ||
123 | Questo è valido per tutte le espressioni che non siano funzioni (if, switch, | |
124 | for, while, do). Per esempio: | |
125 | ||
126 | .. code-block:: c | |
127 | ||
128 | switch (action) { | |
129 | case KOBJ_ADD: | |
130 | return "add"; | |
131 | case KOBJ_REMOVE: | |
132 | return "remove"; | |
133 | case KOBJ_CHANGE: | |
134 | return "change"; | |
135 | default: | |
136 | return NULL; | |
137 | } | |
138 | ||
139 | Tuttavia, c'è il caso speciale, le funzioni: queste hanno la parentesi graffa | |
140 | di apertura all'inizio della riga successiva, quindi: | |
141 | ||
142 | .. code-block:: c | |
143 | ||
144 | int function(int x) | |
145 | { | |
146 | body of function | |
147 | } | |
148 | ||
149 | Eretici da tutto il mondo affermano che questa incoerenza è ... | |
150 | insomma ... incoerente, ma tutte le persone ragionevoli sanno che (a) | |
151 | K&R hanno **ragione** e (b) K&R hanno ragione. A parte questo, le funzioni | |
152 | sono comunque speciali (non potete annidarle in C). | |
153 | ||
154 | Notate che la graffa di chiusura è da sola su una riga propria, ad | |
155 | **eccezione** di quei casi dove è seguita dalla continuazione della stessa | |
156 | espressione, in pratica ``while`` nell'espressione do-while, oppure ``else`` | |
157 | nell'espressione if-else, come questo: | |
158 | ||
159 | .. code-block:: c | |
160 | ||
161 | do { | |
162 | body of do-loop | |
163 | } while (condition); | |
164 | ||
165 | e | |
166 | ||
167 | .. code-block:: c | |
168 | ||
169 | if (x == y) { | |
170 | .. | |
171 | } else if (x > y) { | |
172 | ... | |
173 | } else { | |
174 | .... | |
175 | } | |
176 | ||
177 | Motivazione: K&R. | |
178 | ||
179 | Inoltre, notate che questo posizionamento delle graffe minimizza il numero | |
180 | di righe vuote senza perdere di leggibilità. In questo modo, dato che le | |
181 | righe sul vostro schermo non sono una risorsa illimitata (pensate ad uno | |
182 | terminale con 25 righe), avrete delle righe vuote da riempire con dei | |
183 | commenti. | |
184 | ||
185 | Non usate inutilmente le graffe dove una singola espressione è sufficiente. | |
186 | ||
187 | .. code-block:: c | |
188 | ||
189 | if (condition) | |
190 | action(); | |
191 | ||
192 | e | |
193 | ||
194 | .. code-block:: none | |
195 | ||
196 | if (condition) | |
197 | do_this(); | |
198 | else | |
199 | do_that(); | |
200 | ||
201 | Questo non vale nel caso in cui solo un ramo dell'espressione if-else | |
202 | contiene una sola espressione; in quest'ultimo caso usate le graffe per | |
203 | entrambe i rami: | |
204 | ||
205 | .. code-block:: c | |
206 | ||
207 | if (condition) { | |
208 | do_this(); | |
209 | do_that(); | |
210 | } else { | |
211 | otherwise(); | |
212 | } | |
213 | ||
214 | Inoltre, usate le graffe se un ciclo contiene più di una semplice istruzione: | |
215 | ||
216 | .. code-block:: c | |
217 | ||
218 | while (condition) { | |
219 | if (test) | |
220 | do_something(); | |
221 | } | |
222 | ||
223 | 3.1) Spazi | |
224 | ********** | |
225 | ||
226 | Lo stile del kernel Linux per quanto riguarda gli spazi, dipende | |
227 | (principalmente) dalle funzioni e dalle parole chiave. Usate una spazio dopo | |
228 | (quasi tutte) le parole chiave. L'eccezioni più evidenti sono sizeof, typeof, | |
229 | alignof, e __attribute__, il cui aspetto è molto simile a quello delle | |
230 | funzioni (e in Linux, solitamente, sono usate con le parentesi, anche se il | |
231 | linguaggio non lo richiede; come ``sizeof info`` dopo aver dichiarato | |
232 | ``struct fileinfo info``). | |
233 | ||
234 | Quindi utilizzate uno spazio dopo le seguenti parole chiave:: | |
235 | ||
236 | if, switch, case, for, do, while | |
237 | ||
238 | ma non con sizeof, typeof, alignof, o __attribute__. Ad esempio, | |
239 | ||
240 | .. code-block:: c | |
241 | ||
242 | ||
243 | s = sizeof(struct file); | |
244 | ||
245 | Non aggiungete spazi attorno (dentro) ad un'espressione fra parentesi. Questo | |
246 | esempio è **brutto**: | |
247 | ||
248 | .. code-block:: c | |
249 | ||
250 | ||
251 | s = sizeof( struct file ); | |
252 | ||
253 | Quando dichiarate un puntatore ad una variabile o una funzione che ritorna un | |
254 | puntatore, il posto suggerito per l'asterisco ``*`` è adiacente al nome della | |
255 | variabile o della funzione, e non adiacente al nome del tipo. Esempi: | |
256 | ||
257 | .. code-block:: c | |
258 | ||
259 | ||
260 | char *linux_banner; | |
261 | unsigned long long memparse(char *ptr, char **retptr); | |
262 | char *match_strdup(substring_t *s); | |
263 | ||
264 | Usate uno spazio attorno (da ogni parte) alla maggior parte degli operatori | |
265 | binari o ternari, come i seguenti:: | |
266 | ||
267 | = + - < > * / % | & ^ <= >= == != ? : | |
268 | ||
269 | ma non mettete spazi dopo gli operatori unari:: | |
270 | ||
271 | & * + - ~ ! sizeof typeof alignof __attribute__ defined | |
272 | ||
273 | nessuno spazio dopo l'operatore unario suffisso di incremento o decremento:: | |
274 | ||
275 | ++ -- | |
276 | ||
277 | nessuno spazio dopo l'operatore unario prefisso di incremento o decremento:: | |
278 | ||
279 | ++ -- | |
280 | ||
281 | e nessuno spazio attorno agli operatori dei membri di una struttura ``.`` e | |
282 | ``->``. | |
283 | ||
284 | Non lasciate spazi bianchi alla fine delle righe. Alcuni editor con | |
285 | l'indentazione ``furba`` inseriranno gli spazi bianchi all'inizio di una nuova | |
286 | riga in modo appropriato, quindi potrete scrivere la riga di codice successiva | |
287 | immediatamente. Tuttavia, alcuni di questi stessi editor non rimuovono | |
288 | questi spazi bianchi quando non scrivete nulla sulla nuova riga, ad esempio | |
289 | perché volete lasciare una riga vuota. Il risultato è che finirete per avere | |
290 | delle righe che contengono spazi bianchi in coda. | |
291 | ||
292 | Git vi avviserà delle modifiche che aggiungono questi spazi vuoti di fine riga, | |
293 | e può opzionalmente rimuoverli per conto vostro; tuttavia, se state applicando | |
294 | una serie di modifiche, questo potrebbe far fallire delle modifiche successive | |
295 | perché il contesto delle righe verrà cambiato. | |
296 | ||
297 | 4) Assegnare nomi | |
298 | ----------------- | |
299 | ||
300 | C è un linguaggio spartano, e così dovrebbero esserlo i vostri nomi. Al | |
301 | contrario dei programmatori Modula-2 o Pascal, i programmatori C non usano | |
302 | nomi graziosi come ThisVariableIsATemporaryCounter. Un programmatore C | |
303 | chiamerebbe questa variabile ``tmp``, che è molto più facile da scrivere e | |
304 | non è una delle più difficili da capire. | |
305 | ||
306 | TUTTAVIA, nonostante i nomi con notazione mista siano da condannare, i nomi | |
307 | descrittivi per variabili globali sono un dovere. Chiamare una funzione | |
308 | globale ``pippo`` è un insulto. | |
309 | ||
310 | Le variabili GLOBALI (da usare solo se vi servono **davvero**) devono avere | |
311 | dei nomi descrittivi, così come le funzioni globali. Se avete una funzione | |
312 | che conta gli utenti attivi, dovreste chiamarla ``count_active_users()`` o | |
313 | qualcosa di simile, **non** dovreste chiamarla ``cntusr()``. | |
314 | ||
315 | Codificare il tipo di funzione nel suo nome (quella cosa chiamata notazione | |
316 | ungherese) fa male al cervello - il compilatore conosce comunque il tipo e | |
317 | può verificarli, e inoltre confonde i programmatori. Non c'è da | |
318 | sorprendersi che MicroSoft faccia programmi bacati. | |
319 | ||
320 | Le variabili LOCALI dovrebbero avere nomi corti, e significativi. Se avete | |
321 | un qualsiasi contatore di ciclo, probabilmente sarà chiamato ``i``. | |
322 | Chiamarlo ``loop_counter`` non è produttivo, non ci sono possibilità che | |
323 | ``i`` possa non essere capito. Analogamente, ``tmp`` può essere una qualsiasi | |
324 | variabile che viene usata per salvare temporaneamente un valore. | |
325 | ||
326 | Se avete paura di fare casino coi nomi delle vostre variabili locali, allora | |
327 | avete un altro problema che è chiamato sindrome dello squilibrio dell'ormone | |
328 | della crescita delle funzioni. Vedere il capitolo 6 (funzioni). | |
329 | ||
330 | 5) Definizione di tipi (typedef) | |
331 | -------------------------------- | |
332 | ||
333 | Per favore non usate cose come ``vps_t``. | |
334 | Usare il typedef per strutture e puntatori è uno **sbaglio**. Quando vedete: | |
335 | ||
336 | .. code-block:: c | |
337 | ||
338 | vps_t a; | |
339 | ||
340 | nei sorgenti, cosa significa? | |
341 | Se, invece, dicesse: | |
342 | ||
343 | .. code-block:: c | |
344 | ||
345 | struct virtual_container *a; | |
346 | ||
347 | potreste dire cos'è effettivamente ``a``. | |
348 | ||
349 | Molte persone pensano che la definizione dei tipi ``migliori la leggibilità``. | |
350 | Non molto. Sono utili per: | |
351 | ||
352 | (a) gli oggetti completamente opachi (dove typedef viene proprio usato allo | |
353 | scopo di **nascondere** cosa sia davvero l'oggetto). | |
354 | ||
355 | Esempio: ``pte_t`` eccetera sono oggetti opachi che potete usare solamente | |
356 | con le loro funzioni accessorie. | |
357 | ||
358 | .. note:: | |
359 | Gli oggetti opachi e le ``funzioni accessorie`` non sono, di per se, | |
360 | una bella cosa. Il motivo per cui abbiamo cose come pte_t eccetera è | |
361 | che davvero non c'è alcuna informazione portabile. | |
362 | ||
363 | (b) i tipi chiaramente interi, dove l'astrazione **aiuta** ad evitare | |
364 | confusione sul fatto che siano ``int`` oppure ``long``. | |
365 | ||
366 | u8/u16/u32 sono typedef perfettamente accettabili, anche se ricadono | |
367 | nella categoria (d) piuttosto che in questa. | |
368 | ||
369 | .. note:: | |
370 | ||
371 | Ancora - dev'esserci una **ragione** per farlo. Se qualcosa è | |
372 | ``unsigned long``, non c'è alcun bisogno di avere: | |
373 | ||
374 | typedef unsigned long myfalgs_t; | |
375 | ||
376 | ma se ci sono chiare circostanze in cui potrebbe essere ``unsigned int`` | |
377 | e in altre configurazioni ``unsigned long``, allora certamente typedef | |
378 | è una buona scelta. | |
379 | ||
380 | (c) quando di rado create letteralmente dei **nuovi** tipi su cui effettuare | |
381 | verifiche. | |
382 | ||
383 | (d) circostanze eccezionali, in cui si definiscono nuovi tipi identici a | |
384 | quelli definiti dallo standard C99. | |
385 | ||
386 | Nonostante ci voglia poco tempo per abituare occhi e cervello all'uso dei | |
387 | tipi standard come ``uint32_t``, alcune persone ne obiettano l'uso. | |
388 | ||
389 | Perciò, i tipi specifici di Linux ``u8/u16/u32/u64`` e i loro equivalenti | |
390 | con segno, identici ai tipi standard, sono permessi- tuttavia, non sono | |
391 | obbligatori per il nuovo codice. | |
392 | ||
393 | (e) i tipi sicuri nella spazio utente. | |
394 | ||
395 | In alcune strutture dati visibili dallo spazio utente non possiamo | |
396 | richiedere l'uso dei tipi C99 e nemmeno i vari ``u32`` descritti prima. | |
397 | Perciò, utilizziamo __u32 e tipi simili in tutte le strutture dati | |
398 | condivise con lo spazio utente. | |
399 | ||
400 | Magari ci sono altri casi validi, ma la regola di base dovrebbe essere di | |
401 | non usare MAI MAI un typedef a meno che non rientri in una delle regole | |
402 | descritte qui. | |
403 | ||
404 | In generale, un puntatore, o una struttura a cui si ha accesso diretto in | |
405 | modo ragionevole, non dovrebbero **mai** essere definite con un typedef. | |
406 | ||
407 | 6) Funzioni | |
408 | ----------- | |
409 | ||
410 | Le funzioni dovrebbero essere brevi e carine, e fare una cosa sola. Dovrebbero | |
411 | occupare uno o due schermi di testo (come tutti sappiamo, la dimensione | |
412 | di uno schermo secondo ISO/ANSI è di 80x24), e fare una cosa sola e bene. | |
413 | ||
414 | La massima lunghezza di una funziona è inversamente proporzionale alla sua | |
415 | complessità e al livello di indentazione di quella funzione. Quindi, se avete | |
416 | una funzione che è concettualmente semplice ma che è implementata come un | |
417 | lunga (ma semplice) sequenza di caso-istruzione, dove avete molte piccole cose | |
418 | per molti casi differenti, allora va bene avere funzioni più lunghe. | |
419 | ||
420 | Comunque, se avete una funzione complessa e sospettate che uno studente | |
421 | non particolarmente dotato del primo anno delle scuole superiori potrebbe | |
422 | non capire cosa faccia la funzione, allora dovreste attenervi strettamente ai | |
423 | limiti. Usate funzioni di supporto con nomi descrittivi (potete chiedere al | |
424 | compilatore di renderle inline se credete che sia necessario per le | |
425 | prestazioni, e probabilmente farà un lavoro migliore di quanto avreste potuto | |
426 | fare voi). | |
427 | ||
428 | Un'altra misura delle funzioni sono il numero di variabili locali. Non | |
429 | dovrebbero eccedere le 5-10, oppure state sbagliando qualcosa. Ripensate la | |
430 | funzione, e dividetela in pezzettini. Generalmente, un cervello umano può | |
431 | seguire facilmente circa 7 cose diverse, di più lo confonderebbe. Lo sai | |
432 | d'essere brillante, ma magari vorresti riuscire a capire cos'avevi fatto due | |
433 | settimane prima. | |
434 | ||
435 | Nei file sorgenti, separate le funzioni con una riga vuota. Se la funzione è | |
436 | esportata, la macro **EXPORT** per questa funzione deve seguire immediatamente | |
437 | la riga della parentesi graffa di chiusura. Ad esempio: | |
438 | ||
439 | .. code-block:: c | |
440 | ||
441 | int system_is_up(void) | |
442 | { | |
443 | return system_state == SYSTEM_RUNNING; | |
444 | } | |
445 | EXPORT_SYMBOL(system_is_up); | |
446 | ||
447 | Nei prototipi di funzione, includete i nomi dei parametri e i loro tipi. | |
448 | Nonostante questo non sia richiesto dal linguaggio C, in Linux viene preferito | |
449 | perché è un modo semplice per aggiungere informazioni importanti per il | |
450 | lettore. | |
451 | ||
3d18f586 FV |
452 | Non usate la parola chiave ``extern`` coi prototipi di funzione perché |
453 | rende le righe più lunghe e non è strettamente necessario. | |
454 | ||
edba5eec FV |
455 | 7) Centralizzare il ritorno delle funzioni |
456 | ------------------------------------------ | |
457 | ||
458 | Sebbene sia deprecata da molte persone, l'istruzione goto è impiegata di | |
459 | frequente dai compilatori sotto forma di salto incondizionato. | |
460 | ||
461 | L'istruzione goto diventa utile quando una funzione ha punti d'uscita multipli | |
462 | e vanno eseguite alcune procedure di pulizia in comune. Se non è necessario | |
463 | pulire alcunché, allora ritornate direttamente. | |
464 | ||
465 | Assegnate un nome all'etichetta di modo che suggerisca cosa fa la goto o | |
466 | perché esiste. Un esempio di un buon nome potrebbe essere ``out_free_buffer:`` | |
467 | se la goto libera (free) un ``buffer``. Evitate l'uso di nomi GW-BASIC come | |
468 | ``err1:`` ed ``err2:``, potreste doverli riordinare se aggiungete o rimuovete | |
469 | punti d'uscita, e inoltre rende difficile verificarne la correttezza. | |
470 | ||
471 | I motivo per usare le goto sono: | |
472 | ||
473 | - i salti incondizionati sono più facili da capire e seguire | |
474 | - l'annidamento si riduce | |
475 | - si evita di dimenticare, per errore, di aggiornare un singolo punto d'uscita | |
476 | - aiuta il compilatore ad ottimizzare il codice ridondante ;) | |
477 | ||
478 | .. code-block:: c | |
479 | ||
480 | int fun(int a) | |
481 | { | |
482 | int result = 0; | |
483 | char *buffer; | |
484 | ||
485 | buffer = kmalloc(SIZE, GFP_KERNEL); | |
486 | if (!buffer) | |
487 | return -ENOMEM; | |
488 | ||
489 | if (condition1) { | |
490 | while (loop1) { | |
491 | ... | |
492 | } | |
493 | result = 1; | |
494 | goto out_free_buffer; | |
495 | } | |
496 | ... | |
497 | out_free_buffer: | |
498 | kfree(buffer); | |
499 | return result; | |
500 | } | |
501 | ||
502 | Un baco abbastanza comune di cui bisogna prendere nota è il ``one err bugs`` | |
503 | che assomiglia a questo: | |
504 | ||
505 | .. code-block:: c | |
506 | ||
507 | err: | |
508 | kfree(foo->bar); | |
509 | kfree(foo); | |
510 | return ret; | |
511 | ||
512 | Il baco in questo codice è che in alcuni punti d'uscita la variabile ``foo`` è | |
513 | NULL. Normalmente si corregge questo baco dividendo la gestione dell'errore in | |
514 | due parti ``err_free_bar:`` e ``err_free_foo:``: | |
515 | ||
516 | .. code-block:: c | |
517 | ||
518 | err_free_bar: | |
519 | kfree(foo->bar); | |
520 | err_free_foo: | |
521 | kfree(foo); | |
522 | return ret; | |
523 | ||
524 | Idealmente, dovreste simulare condizioni d'errore per verificare i vostri | |
525 | percorsi d'uscita. | |
526 | ||
527 | ||
528 | 8) Commenti | |
529 | ----------- | |
530 | ||
531 | I commenti sono una buona cosa, ma c'è anche il rischio di esagerare. MAI | |
532 | spiegare COME funziona il vostro codice in un commento: è molto meglio | |
533 | scrivere il codice di modo che il suo funzionamento sia ovvio, inoltre | |
534 | spiegare codice scritto male è una perdita di tempo. | |
535 | ||
536 | Solitamente, i commenti devono dire COSA fa il codice, e non COME lo fa. | |
537 | Inoltre, cercate di evitare i commenti nel corpo della funzione: se la | |
538 | funzione è così complessa che dovete commentarla a pezzi, allora dovreste | |
539 | tornare al punto 6 per un momento. Potete mettere dei piccoli commenti per | |
540 | annotare o avvisare il lettore circa un qualcosa di particolarmente arguto | |
541 | (o brutto), ma cercate di non esagerare. Invece, mettete i commenti in | |
542 | testa alla funzione spiegando alle persone cosa fa, e possibilmente anche | |
543 | il PERCHÉ. | |
544 | ||
545 | Per favore, quando commentate una funzione dell'API del kernel usate il | |
546 | formato kernel-doc. Per maggiori dettagli, leggete i file in | |
547 | :ref::ref:`Documentation/translations/it_IT/doc-guide/ <it_doc_guide>` e in | |
548 | ``script/kernel-doc``. | |
549 | ||
550 | Lo stile preferito per i commenti più lunghi (multi-riga) è: | |
551 | ||
552 | .. code-block:: c | |
553 | ||
554 | /* | |
555 | * This is the preferred style for multi-line | |
556 | * comments in the Linux kernel source code. | |
557 | * Please use it consistently. | |
558 | * | |
559 | * Description: A column of asterisks on the left side, | |
560 | * with beginning and ending almost-blank lines. | |
561 | */ | |
562 | ||
563 | Per i file in net/ e in drivers/net/ lo stile preferito per i commenti | |
564 | più lunghi (multi-riga) è leggermente diverso. | |
565 | ||
566 | .. code-block:: c | |
567 | ||
568 | /* The preferred comment style for files in net/ and drivers/net | |
569 | * looks like this. | |
570 | * | |
571 | * It is nearly the same as the generally preferred comment style, | |
572 | * but there is no initial almost-blank line. | |
573 | */ | |
574 | ||
575 | È anche importante commentare i dati, sia per i tipi base che per tipi | |
576 | derivati. A questo scopo, dichiarate un dato per riga (niente virgole | |
577 | per una dichiarazione multipla). Questo vi lascerà spazio per un piccolo | |
578 | commento per spiegarne l'uso. | |
579 | ||
580 | ||
581 | 9) Avete fatto un pasticcio | |
582 | --------------------------- | |
583 | ||
584 | Va bene, li facciamo tutti. Probabilmente vi è stato detto dal vostro | |
585 | aiutante Unix di fiducia che ``GNU emacs`` formatta automaticamente il | |
586 | codice C per conto vostro, e avete notato che sì, in effetti lo fa, ma che | |
587 | i modi predefiniti non sono proprio allettanti (infatti, sono peggio che | |
588 | premere tasti a caso - un numero infinito di scimmie che scrivono in | |
589 | GNU emacs non faranno mai un buon programma). | |
590 | ||
591 | Quindi, potete sbarazzarvi di GNU emacs, o riconfigurarlo con valori più | |
592 | sensati. Per fare quest'ultima cosa, potete appiccicare il codice che | |
593 | segue nel vostro file .emacs: | |
594 | ||
595 | .. code-block:: none | |
596 | ||
597 | (defun c-lineup-arglist-tabs-only (ignored) | |
598 | "Line up argument lists by tabs, not spaces" | |
599 | (let* ((anchor (c-langelem-pos c-syntactic-element)) | |
600 | (column (c-langelem-2nd-pos c-syntactic-element)) | |
601 | (offset (- (1+ column) anchor)) | |
602 | (steps (floor offset c-basic-offset))) | |
603 | (* (max steps 1) | |
604 | c-basic-offset))) | |
605 | ||
2fec7b33 BVA |
606 | (dir-locals-set-class-variables |
607 | 'linux-kernel | |
608 | '((c-mode . ( | |
609 | (c-basic-offset . 8) | |
610 | (c-label-minimum-indentation . 0) | |
611 | (c-offsets-alist . ( | |
612 | (arglist-close . c-lineup-arglist-tabs-only) | |
613 | (arglist-cont-nonempty . | |
614 | (c-lineup-gcc-asm-reg c-lineup-arglist-tabs-only)) | |
615 | (arglist-intro . +) | |
616 | (brace-list-intro . +) | |
617 | (c . c-lineup-C-comments) | |
618 | (case-label . 0) | |
619 | (comment-intro . c-lineup-comment) | |
620 | (cpp-define-intro . +) | |
621 | (cpp-macro . -1000) | |
622 | (cpp-macro-cont . +) | |
623 | (defun-block-intro . +) | |
624 | (else-clause . 0) | |
625 | (func-decl-cont . +) | |
626 | (inclass . +) | |
627 | (inher-cont . c-lineup-multi-inher) | |
628 | (knr-argdecl-intro . 0) | |
629 | (label . -1000) | |
630 | (statement . 0) | |
631 | (statement-block-intro . +) | |
632 | (statement-case-intro . +) | |
633 | (statement-cont . +) | |
634 | (substatement . +) | |
635 | )) | |
636 | (indent-tabs-mode . t) | |
637 | (show-trailing-whitespace . t) | |
638 | )))) | |
639 | ||
640 | (dir-locals-set-directory-class | |
641 | (expand-file-name "~/src/linux-trees") | |
642 | 'linux-kernel) | |
edba5eec FV |
643 | |
644 | Questo farà funzionare meglio emacs con lo stile del kernel per i file che | |
645 | si trovano nella cartella ``~/src/linux-trees``. | |
646 | ||
647 | Ma anche se doveste fallire nell'ottenere una formattazione sensata in emacs | |
648 | non tutto è perduto: usate ``indent``. | |
649 | ||
650 | Ora, ancora, GNU indent ha la stessa configurazione decerebrata di GNU emacs, | |
651 | ed è per questo che dovete passargli alcune opzioni da riga di comando. | |
652 | Tuttavia, non è così terribile, perché perfino i creatori di GNU indent | |
653 | riconoscono l'autorità di K&R (le persone del progetto GNU non sono cattive, | |
654 | sono solo mal indirizzate sull'argomento), quindi date ad indent le opzioni | |
655 | ``-kr -i8`` (che significa ``K&R, 8 caratteri di indentazione``), o utilizzate | |
656 | ``scripts/Lindent`` che indenterà usando l'ultimo stile. | |
657 | ||
658 | ``indent`` ha un sacco di opzioni, e specialmente quando si tratta di | |
659 | riformattare i commenti dovreste dare un'occhiata alle pagine man. | |
660 | Ma ricordatevi: ``indent`` non è un correttore per una cattiva programmazione. | |
661 | ||
662 | Da notare che potete utilizzare anche ``clang-format`` per aiutarvi con queste | |
663 | regole, per riformattare rapidamente ad automaticamente alcune parti del | |
664 | vostro codice, e per revisionare interi file al fine di identificare errori | |
665 | di stile, refusi e possibilmente anche delle migliorie. È anche utile per | |
666 | ordinare gli ``#include``, per allineare variabili/macro, per ridistribuire | |
667 | il testo e altre cose simili. | |
668 | Per maggiori dettagli, consultate il file | |
669 | :ref:`Documentation/translations/it_IT/process/clang-format.rst <it_clangformat>`. | |
670 | ||
671 | ||
672 | 10) File di configurazione Kconfig | |
673 | ---------------------------------- | |
674 | ||
675 | Per tutti i file di configurazione Kconfig* che si possono trovare nei | |
676 | sorgenti, l'indentazione è un po' differente. Le linee dopo un ``config`` | |
677 | sono indentate con un tab, mentre il testo descrittivo è indentato di | |
678 | ulteriori due spazi. Esempio:: | |
679 | ||
680 | config AUDIT | |
681 | bool "Auditing support" | |
682 | depends on NET | |
683 | help | |
684 | Enable auditing infrastructure that can be used with another | |
685 | kernel subsystem, such as SELinux (which requires this for | |
686 | logging of avc messages output). Does not do system-call | |
687 | auditing without CONFIG_AUDITSYSCALL. | |
688 | ||
689 | Le funzionalità davvero pericolose (per esempio il supporto alla scrittura | |
690 | per certi filesystem) dovrebbero essere dichiarate chiaramente come tali | |
691 | nella stringa di titolo:: | |
692 | ||
693 | config ADFS_FS_RW | |
694 | bool "ADFS write support (DANGEROUS)" | |
695 | depends on ADFS_FS | |
696 | ... | |
697 | ||
698 | Per la documentazione completa sui file di configurazione, consultate | |
cd238eff | 699 | il documento Documentation/kbuild/kconfig-language.rst |
edba5eec FV |
700 | |
701 | ||
702 | 11) Strutture dati | |
703 | ------------------ | |
704 | ||
705 | Le strutture dati che hanno una visibilità superiore al contesto del | |
706 | singolo thread in cui vengono create e distrutte, dovrebbero sempre | |
707 | avere un contatore di riferimenti. Nel kernel non esiste un | |
708 | *garbage collector* (e fuori dal kernel i *garbage collector* sono lenti | |
709 | e inefficienti), questo significa che **dovete** assolutamente avere un | |
710 | contatore di riferimenti per ogni cosa che usate. | |
711 | ||
712 | Avere un contatore di riferimenti significa che potete evitare la | |
713 | sincronizzazione e permette a più utenti di accedere alla struttura dati | |
714 | in parallelo - e non doversi preoccupare di una struttura dati che | |
715 | improvvisamente sparisce dalla loro vista perché il loro processo dormiva | |
716 | o stava facendo altro per un attimo. | |
717 | ||
718 | Da notare che la sincronizzazione **non** si sostituisce al conteggio dei | |
719 | riferimenti. La sincronizzazione ha lo scopo di mantenere le strutture | |
720 | dati coerenti, mentre il conteggio dei riferimenti è una tecnica di gestione | |
721 | della memoria. Solitamente servono entrambe le cose, e non vanno confuse fra | |
722 | di loro. | |
723 | ||
724 | Quando si hanno diverse classi di utenti, le strutture dati possono avere | |
725 | due livelli di contatori di riferimenti. Il contatore di classe conta | |
726 | il numero dei suoi utenti, e il contatore globale viene decrementato una | |
727 | sola volta quando il contatore di classe va a zero. | |
728 | ||
729 | Un esempio di questo tipo di conteggio dei riferimenti multi-livello può | |
730 | essere trovato nella gestore della memoria (``struct mm_sturct``: mm_user e | |
731 | mm_count), e nel codice dei filesystem (``struct super_block``: s_count e | |
732 | s_active). | |
733 | ||
734 | Ricordatevi: se un altro thread può trovare la vostra struttura dati, e non | |
735 | avete un contatore di riferimenti per essa, quasi certamente avete un baco. | |
736 | ||
737 | 12) Macro, enumerati e RTL | |
738 | --------------------------- | |
739 | ||
740 | I nomi delle macro che definiscono delle costanti e le etichette degli | |
741 | enumerati sono scritte in maiuscolo. | |
742 | ||
743 | .. code-block:: c | |
744 | ||
745 | #define CONSTANT 0x12345 | |
746 | ||
747 | Gli enumerati sono da preferire quando si definiscono molte costanti correlate. | |
748 | ||
749 | I nomi delle macro in MAIUSCOLO sono preferibili ma le macro che assomigliano | |
750 | a delle funzioni possono essere scritte in minuscolo. | |
751 | ||
752 | Generalmente, le funzioni inline sono preferibili rispetto alle macro che | |
753 | sembrano funzioni. | |
754 | ||
755 | Le macro che contengono più istruzioni dovrebbero essere sempre chiuse in un | |
756 | blocco do - while: | |
757 | ||
758 | .. code-block:: c | |
759 | ||
760 | #define macrofun(a, b, c) \ | |
761 | do { \ | |
762 | if (a == 5) \ | |
763 | do_this(b, c); \ | |
764 | } while (0) | |
765 | ||
766 | Cose da evitare quando si usano le macro: | |
767 | ||
768 | 1) le macro che hanno effetti sul flusso del codice: | |
769 | ||
770 | .. code-block:: c | |
771 | ||
772 | #define FOO(x) \ | |
773 | do { \ | |
774 | if (blah(x) < 0) \ | |
775 | return -EBUGGERED; \ | |
776 | } while (0) | |
777 | ||
778 | sono **proprio** una pessima idea. Sembra una chiamata a funzione ma termina | |
779 | la funzione chiamante; non cercate di rompere il decodificatore interno di | |
780 | chi legge il codice. | |
781 | ||
782 | 2) le macro che dipendono dall'uso di una variabile locale con un nome magico: | |
783 | ||
784 | .. code-block:: c | |
785 | ||
786 | #define FOO(val) bar(index, val) | |
787 | ||
788 | potrebbe sembrare una bella cosa, ma è dannatamente confusionario quando uno | |
789 | legge il codice e potrebbe romperlo con una cambiamento che sembra innocente. | |
790 | ||
791 | 3) le macro con argomenti che sono utilizzati come l-values; questo potrebbe | |
792 | ritorcervisi contro se qualcuno, per esempio, trasforma FOO in una funzione | |
793 | inline. | |
794 | ||
795 | 4) dimenticatevi delle precedenze: le macro che definiscono espressioni devono | |
796 | essere racchiuse fra parentesi. State attenti a problemi simili con le macro | |
797 | parametrizzate. | |
798 | ||
799 | .. code-block:: c | |
800 | ||
801 | #define CONSTANT 0x4000 | |
802 | #define CONSTEXP (CONSTANT | 3) | |
803 | ||
804 | 5) collisione nello spazio dei nomi quando si definisce una variabile locale in | |
805 | una macro che sembra una funzione: | |
806 | ||
807 | .. code-block:: c | |
808 | ||
809 | #define FOO(x) \ | |
810 | ({ \ | |
811 | typeof(x) ret; \ | |
812 | ret = calc_ret(x); \ | |
813 | (ret); \ | |
814 | }) | |
815 | ||
816 | ret è un nome comune per una variabile locale - __foo_ret difficilmente | |
817 | andrà in conflitto con una variabile già esistente. | |
818 | ||
819 | Il manuale di cpp si occupa esaustivamente delle macro. Il manuale di sviluppo | |
820 | di gcc copre anche l'RTL che viene usato frequentemente nel kernel per il | |
821 | linguaggio assembler. | |
822 | ||
823 | 13) Visualizzare i messaggi del kernel | |
824 | -------------------------------------- | |
825 | ||
826 | Agli sviluppatori del kernel piace essere visti come dotti. Tenete un occhio | |
827 | di riguardo per l'ortografia e farete una belle figura. In inglese, evitate | |
828 | l'uso di parole mozzate come ``dont``: usate ``do not`` oppure ``don't``. | |
829 | Scrivete messaggi concisi, chiari, e inequivocabili. | |
830 | ||
831 | I messaggi del kernel non devono terminare con un punto fermo. | |
832 | ||
833 | Scrivere i numeri fra parentesi (%d) non migliora alcunché e per questo | |
834 | dovrebbero essere evitati. | |
835 | ||
836 | Ci sono alcune macro per la diagnostica in <linux/device.h> che dovreste | |
837 | usare per assicurarvi che i messaggi vengano associati correttamente ai | |
838 | dispositivi e ai driver, e che siano etichettati correttamente: dev_err(), | |
839 | dev_warn(), dev_info(), e così via. Per messaggi che non sono associati ad | |
840 | alcun dispositivo, <linux/printk.h> definisce pr_info(), pr_warn(), pr_err(), | |
841 | eccetera. | |
842 | ||
843 | Tirar fuori un buon messaggio di debug può essere una vera sfida; e quando | |
844 | l'avete può essere d'enorme aiuto per risolvere problemi da remoto. | |
845 | Tuttavia, i messaggi di debug sono gestiti differentemente rispetto agli | |
846 | altri. Le funzioni pr_XXX() stampano incondizionatamente ma pr_debug() no; | |
847 | essa non viene compilata nella configurazione predefinita, a meno che | |
848 | DEBUG o CONFIG_DYNAMIC_DEBUG non vengono impostati. Questo vale anche per | |
849 | dev_dbg() e in aggiunta VERBOSE_DEBUG per aggiungere i messaggi dev_vdbg(). | |
850 | ||
851 | Molti sottosistemi hanno delle opzioni di debug in Kconfig che aggiungono | |
852 | -DDEBUG nei corrispettivi Makefile, e in altri casi aggiungono #define DEBUG | |
853 | in specifici file. Infine, quando un messaggio di debug dev'essere stampato | |
854 | incondizionatamente, per esempio perché siete già in una sezione di debug | |
855 | racchiusa in #ifdef, potete usare printk(KERN_DEBUG ...). | |
856 | ||
857 | 14) Assegnare memoria | |
858 | --------------------- | |
859 | ||
860 | Il kernel fornisce i seguenti assegnatori ad uso generico: | |
861 | kmalloc(), kzalloc(), kmalloc_array(), kcalloc(), vmalloc(), e vzalloc(). | |
678f784c FV |
862 | Per maggiori informazioni, consultate la documentazione dell'API: |
863 | :ref:`Documentation/translations/it_IT/core-api/memory-allocation.rst <it_memory_allocation>` | |
edba5eec FV |
864 | |
865 | Il modo preferito per passare la dimensione di una struttura è il seguente: | |
866 | ||
867 | .. code-block:: c | |
868 | ||
869 | p = kmalloc(sizeof(*p), ...); | |
870 | ||
871 | La forma alternativa, dove il nome della struttura viene scritto interamente, | |
872 | peggiora la leggibilità e introduce possibili bachi quando il tipo di | |
873 | puntatore cambia tipo ma il corrispondente sizeof non viene aggiornato. | |
874 | ||
875 | Il valore di ritorno è un puntatore void, effettuare un cast su di esso è | |
876 | ridondante. La conversione fra un puntatore void e un qualsiasi altro tipo | |
877 | di puntatore è garantito dal linguaggio di programmazione C. | |
878 | ||
879 | Il modo preferito per assegnare un vettore è il seguente: | |
880 | ||
881 | .. code-block:: c | |
882 | ||
883 | p = kmalloc_array(n, sizeof(...), ...); | |
884 | ||
885 | Il modo preferito per assegnare un vettore a zero è il seguente: | |
886 | ||
887 | .. code-block:: c | |
888 | ||
889 | p = kcalloc(n, sizeof(...), ...); | |
890 | ||
891 | Entrambe verificano la condizione di overflow per la dimensione | |
892 | d'assegnamento n * sizeof(...), se accade ritorneranno NULL. | |
893 | ||
678f784c FV |
894 | Questi allocatori generici producono uno *stack dump* in caso di fallimento |
895 | a meno che non venga esplicitamente specificato __GFP_NOWARN. Quindi, nella | |
896 | maggior parte dei casi, è inutile stampare messaggi aggiuntivi quando uno di | |
897 | questi allocatori ritornano un puntatore NULL. | |
898 | ||
edba5eec FV |
899 | 15) Il morbo inline |
900 | ------------------- | |
901 | ||
902 | Sembra che ci sia la percezione errata che gcc abbia una qualche magica | |
903 | opzione "rendimi più veloce" chiamata ``inline``. In alcuni casi l'uso di | |
904 | inline è appropriato (per esempio in sostituzione delle macro, vedi | |
905 | capitolo 12), ma molto spesso non lo è. L'uso abbondante della parola chiave | |
906 | inline porta ad avere un kernel più grande, che si traduce in un sistema nel | |
907 | suo complesso più lento per via di una cache per le istruzioni della CPU più | |
908 | grande e poi semplicemente perché ci sarà meno spazio disponibile per una | |
909 | pagina di cache. Pensateci un attimo; una fallimento nella cache causa una | |
910 | ricerca su disco che può tranquillamente richiedere 5 millisecondi. Ci sono | |
911 | TANTI cicli di CPU che potrebbero essere usati in questi 5 millisecondi. | |
912 | ||
913 | Spesso le persone dicono che aggiungere inline a delle funzioni dichiarate | |
914 | static e utilizzare una sola volta è sempre una scelta vincente perché non | |
915 | ci sono altri compromessi. Questo è tecnicamente vero ma gcc è in grado di | |
916 | trasformare automaticamente queste funzioni in inline; i problemi di | |
917 | manutenzione del codice per rimuovere gli inline quando compare un secondo | |
918 | utente surclassano il potenziale vantaggio nel suggerire a gcc di fare una | |
919 | cosa che avrebbe fatto comunque. | |
920 | ||
921 | 16) Nomi e valori di ritorno delle funzioni | |
922 | ------------------------------------------- | |
923 | ||
924 | Le funzioni possono ritornare diversi tipi di valori, e uno dei più comuni | |
925 | è quel valore che indica se una funzione ha completato con successo o meno. | |
926 | Questo valore può essere rappresentato come un codice di errore intero | |
927 | (-Exxx = fallimento, 0 = successo) oppure un booleano di successo | |
928 | (0 = fallimento, non-zero = successo). | |
929 | ||
930 | Mischiare questi due tipi di rappresentazioni è un terreno fertile per | |
931 | i bachi più insidiosi. Se il linguaggio C includesse una forte distinzione | |
932 | fra gli interi e i booleani, allora il compilatore potrebbe trovare questi | |
933 | errori per conto nostro ... ma questo non c'è. Per evitare di imbattersi | |
934 | in questo tipo di baco, seguite sempre la seguente convenzione:: | |
935 | ||
936 | Se il nome di una funzione è un'azione o un comando imperativo, | |
937 | essa dovrebbe ritornare un codice di errore intero. Se il nome | |
938 | è un predicato, la funzione dovrebbe ritornare un booleano di | |
939 | "successo" | |
940 | ||
941 | Per esempio, ``add work`` è un comando, e la funzione add_work() ritorna 0 | |
942 | in caso di successo o -EBUSY in caso di fallimento. Allo stesso modo, | |
943 | ``PCI device present`` è un predicato, e la funzione pci_dev_present() ritorna | |
944 | 1 se trova il dispositivo corrispondente con successo, altrimenti 0. | |
945 | ||
946 | Tutte le funzioni esportate (EXPORT) devono rispettare questa convenzione, e | |
947 | così dovrebbero anche tutte le funzioni pubbliche. Le funzioni private | |
948 | (static) possono non seguire questa convenzione, ma è comunque raccomandato | |
949 | che lo facciano. | |
950 | ||
951 | Le funzioni il cui valore di ritorno è il risultato di una computazione, | |
952 | piuttosto che l'indicazione sul successo di tale computazione, non sono | |
953 | soggette a questa regola. Solitamente si indicano gli errori ritornando un | |
954 | qualche valore fuori dai limiti. Un tipico esempio è quello delle funzioni | |
955 | che ritornano un puntatore; queste utilizzano NULL o ERR_PTR come meccanismo | |
956 | di notifica degli errori. | |
957 | ||
5eadc169 FV |
958 | 17) L'uso di bool |
959 | ----------------- | |
960 | ||
961 | Nel kernel Linux il tipo bool deriva dal tipo _Bool dello standard C99. | |
962 | Un valore bool può assumere solo i valori 0 o 1, e implicitamente o | |
963 | esplicitamente la conversione a bool converte i valori in vero (*true*) o | |
964 | falso (*false*). Quando si usa un tipo bool il costrutto !! non sarà più | |
965 | necessario, e questo va ad eliminare una certa serie di bachi. | |
966 | ||
967 | Quando si usano i valori booleani, dovreste utilizzare le definizioni di true | |
968 | e false al posto dei valori 1 e 0. | |
969 | ||
970 | Per il valore di ritorno delle funzioni e per le variabili sullo stack, l'uso | |
971 | del tipo bool è sempre appropriato. L'uso di bool viene incoraggiato per | |
972 | migliorare la leggibilità e spesso è molto meglio di 'int' nella gestione di | |
973 | valori booleani. | |
974 | ||
975 | Non usate bool se per voi sono importanti l'ordine delle righe di cache o | |
976 | la loro dimensione; la dimensione e l'allineamento cambia a seconda | |
977 | dell'architettura per la quale è stato compilato. Le strutture che sono state | |
978 | ottimizzate per l'allineamento o la dimensione non dovrebbero usare bool. | |
979 | ||
980 | Se una struttura ha molti valori true/false, considerate l'idea di raggrupparli | |
981 | in un intero usando campi da 1 bit, oppure usate un tipo dalla larghezza fissa, | |
982 | come u8. | |
983 | ||
984 | Come per gli argomenti delle funzioni, molti valori true/false possono essere | |
985 | raggruppati in un singolo argomento a bit denominato 'flags'; spesso 'flags' è | |
986 | un'alternativa molto più leggibile se si hanno valori costanti per true/false. | |
987 | ||
988 | Detto ciò, un uso parsimonioso di bool nelle strutture dati e negli argomenti | |
989 | può migliorare la leggibilità. | |
990 | ||
991 | 18) Non reinventate le macro del kernel | |
edba5eec FV |
992 | --------------------------------------- |
993 | ||
994 | Il file di intestazione include/linux/kernel.h contiene un certo numero | |
995 | di macro che dovreste usare piuttosto che implementarne una qualche variante. | |
996 | Per esempio, se dovete calcolare la lunghezza di un vettore, sfruttate la | |
997 | macro: | |
998 | ||
999 | .. code-block:: c | |
1000 | ||
1001 | #define ARRAY_SIZE(x) (sizeof(x) / sizeof((x)[0])) | |
1002 | ||
1003 | Analogamente, se dovete calcolare la dimensione di un qualche campo di una | |
1004 | struttura, usate | |
1005 | ||
1006 | .. code-block:: c | |
1007 | ||
1008 | #define FIELD_SIZEOF(t, f) (sizeof(((t*)0)->f)) | |
1009 | ||
1010 | Ci sono anche le macro min() e max() che, se vi serve, effettuano un controllo | |
1011 | rigido sui tipi. Sentitevi liberi di leggere attentamente questo file | |
1012 | d'intestazione per scoprire cos'altro è stato definito che non dovreste | |
1013 | reinventare nel vostro codice. | |
1014 | ||
5eadc169 | 1015 | 19) Linee di configurazione degli editor e altre schifezze |
edba5eec FV |
1016 | ----------------------------------------------------------- |
1017 | ||
1018 | Alcuni editor possono interpretare dei parametri di configurazione integrati | |
1019 | nei file sorgenti e indicati con dai marcatori speciali. Per esempio, emacs | |
1020 | interpreta le linee marcate nel seguente modo: | |
1021 | ||
1022 | .. code-block:: c | |
1023 | ||
1024 | -*- mode: c -*- | |
1025 | ||
1026 | O come queste: | |
1027 | ||
1028 | .. code-block:: c | |
1029 | ||
1030 | /* | |
1031 | Local Variables: | |
1032 | compile-command: "gcc -DMAGIC_DEBUG_FLAG foo.c" | |
1033 | End: | |
1034 | */ | |
1035 | ||
1036 | Vim interpreta i marcatori come questi: | |
1037 | ||
1038 | .. code-block:: c | |
1039 | ||
1040 | /* vim:set sw=8 noet */ | |
1041 | ||
1042 | Non includete nessuna di queste cose nei file sorgenti. Le persone hanno le | |
1043 | proprie configurazioni personali per l'editor, e i vostri sorgenti non | |
1044 | dovrebbero sovrascrivergliele. Questo vale anche per i marcatori | |
1045 | d'indentazione e di modalità d'uso. Le persone potrebbero aver configurato una | |
1046 | modalità su misura, oppure potrebbero avere qualche altra magia per far | |
1047 | funzionare bene l'indentazione. | |
1048 | ||
5eadc169 FV |
1049 | 20) Inline assembly |
1050 | ------------------- | |
edba5eec FV |
1051 | |
1052 | Nel codice specifico per un'architettura, potreste aver bisogno di codice | |
1053 | *inline assembly* per interfacciarvi col processore o con una funzionalità | |
1054 | specifica della piattaforma. Non esitate a farlo quando è necessario. | |
1055 | Comunque, non usatele gratuitamente quando il C può fare la stessa cosa. | |
1056 | Potete e dovreste punzecchiare l'hardware in C quando è possibile. | |
1057 | ||
1058 | Considerate la scrittura di una semplice funzione che racchiude pezzi comuni | |
1059 | di codice assembler piuttosto che continuare a riscrivere delle piccole | |
1060 | varianti. Ricordatevi che l' *inline assembly* può utilizzare i parametri C. | |
1061 | ||
1062 | Il codice assembler più corposo e non banale dovrebbe andare nei file .S, | |
1063 | coi rispettivi prototipi C definiti nei file d'intestazione. I prototipi C | |
1064 | per le funzioni assembler dovrebbero usare ``asmlinkage``. | |
1065 | ||
1066 | Potreste aver bisogno di marcare il vostro codice asm come volatile al fine | |
1067 | d'evitare che GCC lo rimuova quando pensa che non ci siano effetti collaterali. | |
1068 | Non c'è sempre bisogno di farlo, e farlo quando non serve limita le | |
1069 | ottimizzazioni. | |
1070 | ||
1071 | Quando scrivete una singola espressione *inline assembly* contenente più | |
1072 | istruzioni, mettete ognuna di queste istruzioni in una stringa e riga diversa; | |
1073 | ad eccezione dell'ultima stringa/istruzione, ognuna deve terminare con ``\n\t`` | |
1074 | al fine di allineare correttamente l'assembler che verrà generato: | |
1075 | ||
1076 | .. code-block:: c | |
1077 | ||
1078 | asm ("magic %reg1, #42\n\t" | |
1079 | "more_magic %reg2, %reg3" | |
1080 | : /* outputs */ : /* inputs */ : /* clobbers */); | |
1081 | ||
5eadc169 | 1082 | 21) Compilazione sotto condizione |
edba5eec FV |
1083 | --------------------------------- |
1084 | ||
1085 | Ovunque sia possibile, non usate le direttive condizionali del preprocessore | |
1086 | (#if, #ifdef) nei file .c; farlo rende il codice difficile da leggere e da | |
1087 | seguire. Invece, usate queste direttive nei file d'intestazione per definire | |
1088 | le funzioni usate nei file .c, fornendo i relativi stub nel caso #else, | |
1089 | e quindi chiamate queste funzioni senza condizioni di preprocessore. Il | |
1090 | compilatore non produrrà alcun codice per le funzioni stub, produrrà gli | |
1091 | stessi risultati, e la logica rimarrà semplice da seguire. | |
1092 | ||
1093 | È preferibile non compilare intere funzioni piuttosto che porzioni d'esse o | |
1094 | porzioni d'espressioni. Piuttosto che mettere una ifdef in un'espressione, | |
1095 | fattorizzate parte dell'espressione, o interamente, in funzioni e applicate | |
1096 | la direttiva condizionale su di esse. | |
1097 | ||
1098 | Se avete una variabile o funzione che potrebbe non essere usata in alcune | |
1099 | configurazioni, e quindi il compilatore potrebbe avvisarvi circa la definizione | |
1100 | inutilizzata, marcate questa definizione come __maybe_used piuttosto che | |
1101 | racchiuderla in una direttiva condizionale del preprocessore. (Comunque, | |
1102 | se una variabile o funzione è *sempre* inutilizzata, rimuovetela). | |
1103 | ||
1104 | Nel codice, dov'è possibile, usate la macro IS_ENABLED per convertire i | |
1105 | simboli Kconfig in espressioni booleane C, e quindi usatela nelle classiche | |
1106 | condizioni C: | |
1107 | ||
1108 | .. code-block:: c | |
1109 | ||
1110 | if (IS_ENABLED(CONFIG_SOMETHING)) { | |
1111 | ... | |
1112 | } | |
1113 | ||
1114 | Il compilatore valuterà la condizione come costante (constant-fold), e quindi | |
1115 | includerà o escluderà il blocco di codice come se fosse in un #ifdef, quindi | |
1116 | non ne aumenterà il tempo di esecuzione. Tuttavia, questo permette al | |
1117 | compilatore C di vedere il codice nel blocco condizionale e verificarne la | |
1118 | correttezza (sintassi, tipi, riferimenti ai simboli, eccetera). Quindi | |
1119 | dovete comunque utilizzare #ifdef se il codice nel blocco condizionale esiste | |
1120 | solo quando la condizione è soddisfatta. | |
1121 | ||
1122 | Alla fine di un blocco corposo di #if o #ifdef (più di alcune linee), | |
1123 | mettete un commento sulla stessa riga di #endif, annotando la condizione | |
1124 | che termina. Per esempio: | |
1125 | ||
1126 | .. code-block:: c | |
1127 | ||
1128 | #ifdef CONFIG_SOMETHING | |
1129 | ... | |
1130 | #endif /* CONFIG_SOMETHING */ | |
1131 | ||
1132 | Appendice I) riferimenti | |
1133 | ------------------------ | |
1134 | ||
1135 | The C Programming Language, Second Edition | |
1136 | by Brian W. Kernighan and Dennis M. Ritchie. | |
1137 | Prentice Hall, Inc., 1988. | |
1138 | ISBN 0-13-110362-8 (paperback), 0-13-110370-9 (hardback). | |
1139 | ||
1140 | The Practice of Programming | |
1141 | by Brian W. Kernighan and Rob Pike. | |
1142 | Addison-Wesley, Inc., 1999. | |
1143 | ISBN 0-201-61586-X. | |
1144 | ||
1145 | Manuali GNU - nei casi in cui sono compatibili con K&R e questo documento - | |
1146 | per indent, cpp, gcc e i suoi dettagli interni, tutto disponibile qui | |
1147 | http://www.gnu.org/manual/ | |
1148 | ||
1149 | WG14 è il gruppo internazionale di standardizzazione per il linguaggio C, | |
1150 | URL: http://www.open-std.org/JTC1/SC22/WG14/ | |
1151 | ||
1152 | Kernel process/coding-style.rst, by greg@kroah.com at OLS 2002: | |
1153 | http://www.kroah.com/linux/talks/ols_2002_kernel_codingstyle_talk/html/ |