[Ainulindale-devel] Stile di programmazione

[Federico 'Derfel' Stella]

Come richiesto ho scritto un breve documento contenente lo stile di
programmazione che si dovrebbe utilizzare per questo progetto. Sto anche
lavorando ad un script che correggerà il codice indentato male.

Mi piacerebbe avere un riscontro da tutti con esempi di codice per le varie
sezioni, in modo da essere sicuro di aver spiegato i concetti in modo
chiaro.

Non è in allegato per facilitarvi i commenti.

+++

                Stile di Programmazione per Ainulindale

Questo è un breve documento che illustra lo stile di programmazione preferito
per Ainulindale. Lo stile di programmazione è molto personale, ma per la
cresita di un progetto è necessario seguire le regole quando possibile.

                Capitolo 1: Indentatura

Un tab equivale a 8 caratteri, e quindi si indenta con 8 caratteri.
Ci sono movimenti eretici che indentano con 4 (o addirittura 2!) caratteri ed
è un po' come definire 3 il valore di PI.

Gli operatori vanno preceduti e seguiti da spazi.
Le virgole ed i punti virgola vengono solo fatti seguire da spazi.

                Capitolo 2: Posizionare le parentesi

Le parentesi non vanno spostate su una linea vuota, ma lasciate in fondo alla
linea. Fa eccezione la dichiarazione di funzione in cui la parentesi di apertura
va posta su una nuova linea.

La coppia di parentesi tonde aperta-chiusa va circondata da spazi all'esterno.

Le parentesi di chiusura vanno messe in una linea vuota all'altezza del codice
che le apre. Si può scrivere codice dopo le parentesi di chiusura quando questo
continua e/o completa il blocco del codice.

                Capitolo 3: Naming

Per le variabili si usano solo caratteri minuscoli, mentre per enumerativi e
costanti solo maiuscole.

Le variabili locali dovrebbere essere corte e coincise, mentre dare un nome
descrittivo alle variabili globali è un obbligo.
Quando il nome di una variabile è composto da più parole si usano gli underscore
per separarle.

La notazione ungherese è proibita.

                Capitolo 4: Funzioni

Una funziona deve essere semplice, lineare e fare una sola cosa.

Se c'è una funzione complicata che non può essere compresa al volo deve essere
spezzata utilizzando delle funzioni d'appoggio (potete renderle inline se è
critica per le prestazioni).

                Capitolo 5: Commenti

I commenti sono una buona cosa, ma non bisogna commentare troppo. Non cercate
di spiegare come il vostro codice funziona in un commento: è meglio scrivere
in modo che sia ovvio come lavori. È una perdita di tempo cercare di commentare
codice scritto male.

In generale, in un commento di dovrebbe spiegare cosa quel codice farà e non
come. Normalmente i commenti all'interno di una funzione non sono necessari,
se così non fosse potrebbe essere utile rileggere il capitolo 4. È comunque
possibile inserire brevi commenti per qualcosa di particolarmente intelligente
o di particolarmente stupido. Inserite invece i commenti prima della funzione
spiegando in maniera semplice cosa faccia il codi in questione e sopratutto
perché.

Se non indispendabile non mettete i commenti in linee che contengono codice, ma
sulla linea precedente.