path: root/Documentation/translations/it_IT/process/coding-style.rst

.. include:: ../disclaimer-ita.rst

:Original: :ref:`Documentation/process/coding-style.rst <codingstyle>`
:Translator: Federico Vaga <federico.vaga@vaga.pv.it>

.. _it_codingstyle:

Stile del codice per il kernel Linux
====================================

Questo è un breve documento che descrive lo stile di codice preferito per
il kernel Linux.  Lo stile di codifica è molto personale e non voglio
**forzare** nessuno ad accettare il mio, ma questo stile è quello che
dev'essere usato per qualsiasi cosa che io sia in grado di mantenere, e l'ho
preferito anche per molte altre cose.  Per favore, almeno tenete in
considerazione le osservazioni espresse qui.

La prima cosa che suggerisco è quella di stamparsi una copia degli standard
di codifica GNU e di NON leggerla.  Bruciatela, è un grande gesto simbolico.

Comunque, ecco i punti:

1) Indentazione
---------------

La tabulazione (tab) è di 8 caratteri e così anche le indentazioni. Ci sono
alcuni movimenti di eretici che vorrebbero l'indentazione a 4 (o perfino 2!)
caratteri di profondità, che è simile al tentativo di definire il valore del
pi-greco a 3.

Motivazione: l'idea dell'indentazione è di definire chiaramente dove un blocco
di controllo inizia e finisce.  Specialmente quando siete rimasti a guardare lo
schermo per 20 ore a file, troverete molto più facile capire i livelli di
indentazione se questi sono larghi.

Ora, alcuni rivendicano che un'indentazione da 8 caratteri sposta il codice
troppo a destra e che quindi rende difficile la lettura su schermi a 80
caratteri.  La risposta a questa affermazione è che se vi servono più di 3
livelli di indentazione, siete comunque fregati e dovreste correggere il vostro
programma.

In breve, l'indentazione ad 8 caratteri rende più facile la lettura, e in
aggiunta vi avvisa quando state annidando troppo le vostre funzioni.
Tenete ben a mente questo avviso.

Al fine di facilitare l'indentazione del costrutto switch, si preferisce
allineare sulla stessa colonna la parola chiave ``switch`` e i suoi
subordinati ``case``. In questo modo si evita una doppia indentazione per
i ``case``.  Un esempio.:

.. code-block:: c

	switch (suffix) {
	case 'G':
	case 'g':
		mem <<= 30;
		break;
	case 'M':
	case 'm':
		mem <<= 20;
		break;
	case 'K':
	case 'k':
		mem <<= 10;
		/* fall through */
	default:
		break;
	}

A meno che non vogliate nascondere qualcosa, non mettete più istruzioni sulla
stessa riga:

.. code-block:: c

	if (condition) do_this;
	  do_something_everytime;

né mettete più assegnamenti sulla stessa riga.  Lo stile del kernel
è ultrasemplice.  Evitate espressioni intricate.

Al di fuori dei commenti, della documentazione ed escludendo i Kconfig, gli
spazi non vengono mai usati per l'indentazione, e l'esempio qui sopra è
volutamente errato.

Procuratevi un buon editor di testo e non lasciate spazi bianchi alla fine
delle righe.


2) Spezzare righe lunghe e stringhe
-----------------------------------

Lo stile del codice riguarda la leggibilità e la manutenibilità utilizzando
strumenti comuni.

Il limite delle righe è di 80 colonne e questo e un limite fortemente
desiderato.

Espressioni più lunghe di 80 colonne saranno spezzettate in pezzi più piccoli,
a meno che eccedere le 80 colonne non aiuti ad aumentare la leggibilità senza
nascondere informazioni.  I pezzi derivati sono sostanzialmente più corti degli
originali e vengono posizionati più a destra.  Lo stesso si applica, nei file
d'intestazione, alle funzioni con una lista di argomenti molto lunga. Tuttavia,
non spezzettate mai le stringhe visibili agli utenti come i messaggi di
printk, questo perché inibireste la possibilità d'utilizzare grep per cercarle.

3) Posizionamento di parentesi graffe e spazi
---------------------------------------------

Un altro problema che s'affronta sempre quando si parla di stile in C è
il posizionamento delle parentesi graffe.  Al contrario della dimensione
dell'indentazione, non ci sono motivi tecnici sulla base dei quali scegliere
una strategia di posizionamento o un'altra; ma il modo qui preferito,
come mostratoci dai profeti Kernighan e Ritchie, è quello di
posizionare la parentesi graffa di apertura per ultima sulla riga, e quella
di chiusura per prima su una nuova riga, così:

.. code-block:: c

	if (x is true) {
		we do y
	}

Questo è valido per tutte le espressioni che non siano funzioni (if, switch,
for, while, do).  Per esempio:

.. code-block:: c

	switch (action) {
	case KOBJ_ADD:
		return "add";
	case KOBJ_REMOVE:
		return "remove";
	case KOBJ_CHANGE:
		return "change";
	default:
		return NULL;
	}

Tuttavia, c'è il caso speciale, le funzioni: queste hanno la parentesi graffa
di apertura all'inizio della riga successiva, quindi:

.. code-block:: c

	int function(int x)
	{
		body of function
	}

Eretici da tutto il mondo affermano che questa incoerenza è ...
insomma ... incoerente, ma tutte le persone ragionevoli sanno che (a)
K&R hanno **ragione** e (b) K&R hanno ragione.  A parte questo, le funzioni
sono comunque speciali (non potete annidarle in C).

Notate che la graffa di chiusura è da sola su una riga propria, ad
**eccezione** di quei casi dove è seguita dalla continuazione della stessa
espressione, in pratica ``while`` nell'espressione do-while, oppure ``else``
nell'espressione if-else, come questo:

.. code-block:: c

	do {
		body of do-loop
	} while (condition);

e

.. code-block:: c

	if (x == y) {
		..
	} else if (x > y) {
		...
	} else {
		....
	}

Motivazione: K&R.

Inoltre, notate che questo posizionamento delle graffe minimizza il numero
di righe vuote senza perdere di leggibilità.  In questo modo, dato che le
righe sul vostro schermo non sono una risorsa illimitata (pensate ad uno
terminale con 25 righe), avrete delle righe vuote da riempire con dei
commenti.

Non usate inutilmente le graffe dove una singola espressione è sufficiente.

.. code-block:: c

	if (condition)
		action();

e

.. code-block:: none

	if (condition)
		do_this();
	else
		do_that();

Questo non vale nel caso in cui solo un ramo dell'espressione if-else
contiene una sola espressione; in quest'ultimo caso usate le graffe per
entrambe i rami:

.. code-block:: c

	if (condition) {
		do_this();
		do_that();
	} else {
		otherwise();
	}

Inoltre, usate le graffe se un ciclo contiene più di una semplice istruzione:

.. code-block:: c

	while (condition) {
		if (test)
			do_something();
	}

3.1) Spazi
**********

Lo stile del kernel Linux per quanto riguarda gli spazi, dipende
(principalmente) dalle funzioni e dalle parole chiave.  Usate una spazio dopo
(quasi tutte) le parole chiave.  L'eccezioni più evidenti sono sizeof, typeof,
alignof, e __attribute__, il cui aspetto è molto simile a quello delle
funzioni (e in Linux, solitamente, sono usate con le parentesi, anche se il
linguaggio non lo richiede; come ``sizeof info`` dopo aver dichiarato
``struct fileinfo info``).

Quindi utilizzate uno spazio dopo le seguenti parole chiave::

	if, switch, case, for, do, while

ma non con sizeof, typeof, alignof, o __attribute__.  Ad esempio,

.. code-block:: c


	s = sizeof(struct file);

Non aggiungete spazi attorno (dentro) ad un'espressione fra parentesi. Questo
esempio è **brutto**:

.. code-block:: c


	s = sizeof( struct file );

Quando dichiarate un puntatore ad una variabile o una funzione che ritorna un
puntatore, il posto suggerito per l'asterisco ``*`` è adiacente al nome della
variabile o della funzione, e non adiacente al nome del tipo. Esempi:

.. code-block:: c


	char *linux_banner;
	unsigned long long memparse(char *ptr, char **retptr);
	char *match_strdup(substring_t *s);

Usate uno spazio attorno (da ogni parte) alla maggior parte degli operatori
binari o ternari, come i seguenti::

	=  +  -  <  >  *  /  %  |  &  ^  <=  >=  ==  !=  ?  :

ma non mettete spazi dopo gli operatori unari::

	&  *  +  -  ~  !  sizeof  typeof  alignof  __attribute__  defined

nessuno spazio dopo l'operatore unario suffisso di incremento o decremento::

	++  --

nessuno spazio dopo