Download Documentazione FAQ Aiutaci!!!
PEP:8
Titolo:Guida allo stile per il codice Python
Versione:1.3
AutoreGuido van Rossum (guido at python.org), Barry Warsaw (barry at digicool.com)
Status:Attiva
Tipo:Informativa
Creazione:5 Luglio 2001
Traduzione:Alex Martelli (aleaxit at yahoo.com) - 5 Luglio 2001

Introduzione

Questo documento presenta le convenzioni di codifica per il codice Python della libreria standard nella distribuzione di Python. Vedi anche le PEP 7 (guida di stile per il codice C nella implementazione C di Python) e 257 (convenzioni sulle docstring).

La fonte originale del documento è il saggio di Guido sullo stile in Python. Questa PEP eredita l'incompletezza di quel saggio.

Una Sciocca Coerenza è l'Orco delle Menti Piccole

Una guida allo stile riguarda la coerenza. è importante essere coerenti con questa guida allo stile. È più importante essere coerenti all'interno di un dato progetto. La cosa più importante è essere coerenti entro un singolo modulo o funzione. E la più importante di tutte: sappi quando essere incoerente, a volte la guida allo stile non si applica. Nel dubbio, usa il tuo giudizio. Guarda altri esempi e decidi cosa sembra meglio. E non esitare a chiedere!

Due buone ragioni per violare una data regola:

  1. quando applicando la regola si avrebbe codice meno leggibile, anche per qualcuno abituato a leggere codice che segue le regole
  2. per essere coerente con codice nelle vicinanze che pure viola la regola (magari per ragioni storiche), ma questa è anche un'opportunità per ripulire da brutture il codice di qualcun altro, nel più vero stile eXtreme Programming.

Lay-out del codice

Indentazione

Usa la scelta predefinita del modo Python di Emacs: quattro spazi per ogni livello di indentazione. In caso di codice davvero datato, per non incasinarlo puoi continuare a usare le tabulazioni da otto spazi.

Il modo Python si accorge automaticamente del livello d'indentazione usato in prevalenza in un file e vi si accorda.

Tabulazioni o spazi?

Non mescolare mai tab e spazi. Il modo più popolare di indentare Python è con soli spazi. Alcuni programmatori usano solo i tab. Codice indentato con un misto di tab e spazi dovrebbe essere convertito all'uso degli spazi (in Emacs, selezionare tutto il buffer e poi dare ESC-x untabify). Quando chiami l'interprete python da riga di comando con opzione -t, dà dei warning per codice che mescola spazi e tab in maniera ambigua; con -tt, errori. Sono opzioni altamente raccomandate!

Lunghezza massima delle righe

Vi sono molte periferiche limitate a righe di 80 caratteri. Linee più lunghe su queste periferiche sono "ripiegate" e risultano assai brutte. Limita dunque ogni linea a un massimo di 79 caratteri (una linea di esattamente 80 caratteri rischierebbe infatti di venire comunque ripiegata).

Il modo migliore di dividere linee lunghe è usare la continuazione implicita di Python fra parentesi tonde, quadre e graffe. Se occorre aggiungi un paio supplementare di parentesi attorno a un'espressione (qualche rara volta usare una barra obliqua inversa [`backslash'] ha un aspetto migliore).

Ricordati di indentare bene la riga continuata. Il modo Python di Emacs lo fa. Esempi:

class Rectangle(Blob):

        def __init__(self, width, height,
                     color='black', emphasis=None, highlight=0):
            if width == 0 and height == 0 and \
               color == 'red' and emphasis == 'strong' or \
               highlight > 100:
                raise ValueError, "sorry, you lose"
            if width == 0 and height == 0 and (color == 'red' or
                                               emphasis is None):
                raise ValueError, "I don't think so"
            Blob.__init__(self, width, height,
                          color, emphasis, highlight)

Righe bianche

Separa le definizioni di funzioni e classe a top-level con due righe bianche. Separa le definizioni di metodi entro una classe con una sola riga bianca. Puoi usare (moderatamente) altre righe bianche per separare gruppi di funzioni imparentate. Puoi omettere le righe bianche fra un mucchio di righe singole imparentate fra loro (ad es. un tot di implementazioni fittizie).

Quando usi righe bianche per separare le definizioni di metodi, usa anche una riga bianca fra la riga 'class' e la definizione del primo metodo.

Usa righe bianche all'interno delle funzioni, moderatamente, per indicare sezioni logiche.

Python accetta il carattere di salto pagina (CTRL-L) come spazio bianco; Emacs e alcune stampanti trattano questo carattere come separatore di pagina, quindi puoi usarlo per separare pagine di sezioni imparentate del tuo file.

Spazio bianco in Espressioni e Istruzioni

Da Evitare

Guido odia lo spazio bianco nei seguenti posti:
  • immediatamente entro parentesi tonde, quadre o graffe, tipo: "spam( ham[ 1 ], { eggs: 2 } )". Scrivi invece sempre "spam(ham[1], {eggs: 2})".
  • subito prima di virgola, punto e virgola, o due punti, tipo: "if x == 4 : print x , y ; x , y = y , x". Scrivi invece sempre "if x == 4: print x, y; x, y = y, x".
  • subito prima della parentesi aperta che inizia la lista degli argomenti in una chiamata, tipo "spam (1)". Scrivi invece sempre "spam(1)".
  • subito prima della quadra aperta che inizia un indicizzazione o affettamento, tipo "dict ['key'] = list [index]". Scrivi invece sempre "dict['key'] = list[index]".
  • più di uno spazio attorno a un assegnamento o operatore per allinearlo con altri, tipo:
    x             = 1 
    y             = 2 
    long_variable = 3
    
    Scrivi invece sempre
    x = 1 
    y = 2 
    long_variable = 3
    
Inutile discutere di questi temi: Guido si è abituato a questo stile da 15 anni a questa parte.

Altre raccomandazioni

  • circonda sempre questi operatori binari con un singolo spazio da ciascuna parte: assegnamento (=), confronti (==, <, >, !=, <>, <=, >=, in, not in, is, is not), booleani (and, or, not).
  • usa giudizio per inserire spazi attorno agli operatori aritmetici. Sii sempre coerente sullo spazio sui due lati di un operatore binario. Alcuni buoni esempi:
    i = i+1 
    submitted = submitted + 1 
    x = x*2 - 1 
    hypot2 = x*x + y*y 
    c = (a+b) * (a-b) 
    c = (a + b) * (a - b)
    
  • non usare mai spazi attorno al segno '=' quando lo usi per indicare un argomento con nome o il valore di default di un argomento. Per esempio:
    def complex(real, imag=0.0): 
        return magic(r=real, i=imag)
    

Commenti

Commenti che contraddicono il codice sono molto peggio che non avere commenti. La priorità assoluta deve sempre essere di tenere aggiornati i commenti quando il codice cambia!

Se un commento è una frase o periodo, la prima parola deve iniziare con una lettera maiuscola, ECCETTO il caso in cui si tratti di un identificatore che inizia con minuscola (NON alterare MAI le minuscole/maiuscole negli identificatori!).

Se un commento è breve, meglio omettere il punto fermo alla fine. I commenti a blocco generalmente consistono di uno o più paragrafi fatti di frasi complete, e ogni frase dovrebbe finire con un punto fermo. Puoi usare due spazi dopo il punto fermo che chiude una frase.

Come sempre quando scrivi in inglese, applica Strunk e White [autori di un classico manuale di stile della lingua inglese NdT].

Chi scrive in Python e viene da un paese non di lingua inglese: scrivi i commenti comunque in inglese, a meno che tu non sia sicuro al 120% che il codice non verrà mai letto da persone che non parlano la tua lingua.

Commenti a blocco

I commenti a blocco si applicano a codice che li segue, e vanno indentati esattamente come quel codice. Ogni riga di un commento a blocco inizia con # seguito da un singolo spazio (a meno che non si tratti di testo indentato entro il commento). I paragrafi entro un commento a blocco sono separati da una riga che contiene soltanto un #. È meglio circondare i commenti a blocco con una riga bianca sopra e una sotto (o due righe sopra e una sotto per un commento a blocco che è all'inizio di una nuova sezione di definizione di funzioni).

Commenti in linea

Un commento in linea è un commento sulla stessa riga di una istruzione. I commenti in linea vanno usati con moderazione. I commenti in linea dovrebbero essere separati da almeno due spazi dall'istruzione. Dovrebbero iniziare con un # seguito da un singolo spazio.

I commenti in linea sono inutili e in effetti distraggono se ridicono l'ovvio. Non perpetrare MAI assurdità del tipo:

    x = x+1 # Incrementa x
Ma qualche rara volta, possono essere utili:
    x = x+1 # Compensa per il bordo

Stringhe di documentazione

Le convenzioni per scrivere buone stringhe di documentazione (docstring) sono immortalate alla PEP 257.

Burocrazie di versione

Se devi avere robaccia RCS o CVS nel tuo sorgente, fai così:
    __version__ = "$Revision: 1.3 $" 
    # $Source: /cvsroot/python/python/nondist/peps/pep-0008.txt,v $
Queste linee devono essere dopo la docstring del modulo, prima di qualsiasi altro codice, separate da una riga bianca prima e dopo.

Convenzioni sui nomi

Le convenzioni sui nomi nella libreria di Python sono un po' un casino, e non le sistemeremo mai del tutto; nondimeno, ci sono alcune linee guida.

Descrittivo: Stili dei Nomi

Ci sono molti diversi stili per i nomi. è importante sapere riconoscere quale stile viene usato, indipendentemente dalla ragione per cui viene usato.

Distinguiamo normalmente i seguenti stili:

  • x (unica lettera minuscola)
  • X (unica lettera maiuscola)
  • minuscole
  • minuscole_con_sottolineature
  • MAIUSCOLE
  • MAIUSCOLE_CON_SOTTOLINEATURE
  • ParoleCapitalizzate (o ParoCap)
  • stileMisto (differisce da ParoCap perché la prima lettera è minuscola)
  • Parole_Capitalizzate_Con_Sottolineature (brutto!)
C'è anche lo stile di usare un breve prefisso unico per raggruppare nomi imparentati. Questo non si usa molto in Python, ma lo nomino per completezza. Per esempio, la funzione os.stat restituisce una tupla i cui elementi tradizionalmente hanno nomi come st_mode, st_size, st_mtime e così via. La libreria X11 usa una X iniziale per tutte le sue funzioni pubbliche. In Python questo stile è generalmente considerato inutile perché i nomi di attributi e metodi hanno come prefisso un oggetto, e i nomi di funzione hanno come prefisso il nome di un modulo.

Inoltre, riconosciamo le seguenti forme speciali che usano sottolineature iniziali o finali (possono generalmente venire combinate con qualsiasi convenzione sulle maiuscole/minuscole):

  • _una_sottolineatura_iniziale: indicatore debole di "uso interno" (ad es., "from M import *" non importa gli oggetti i cui nomi iniziano con sottolineatura)
  • una_sottolineatura_finale_: usato per convenzione per evitare conflitti con parole riservate Python, a es. "Tkinter.Toplevel(master, class_='ClassName')".
  • __due_sottolineature_iniziali: nomi privati a una classe, sin dai tempi di Python 1.4
  • __due_sottolineature_davanti_e_dietro__: oggetti o attributi "magici" che vivono in spazi dei nomi controllati dall'utente, a es. __init__, __import__ or __file__. A volte sono definiti dall'utente per ottenere un qualche comportamento magico (ad es. il sovraccaricamento [`overloading'] di operatori); a volte sono inseriti dall'infrastruttura per i propri usi o a scopi di debug. Poiché l'infrastruttura (l'interprete Python e la libreria standard)può decidere a qualunque release di aumentare la propria lista di attributi magici, il codice utente dovrebbe generalmente evitare di usare questa convenzione per proprio uso. Il codice utente che mira a divenire parte dell'infrastruttura potrebbe combinare questo con un breve prefisso dopo le sottolineature, tipo __bobo_magic_attr__.

Prescrittivo: Convenzioni sui Nomi

Nomi di modulo

I nomi di modulo possono essere ParoCap o minuscoli. Non vi è convenzione priva di ambiguità per decidere quale usare. I moduli che esportano una singola classe (o un piccolo numero di classi strettamente imparentate, più un qualche appoggio supplementare) sono spesso ParoCap, col nome del modulo eguale al nome della classe (a es. il modulo standard StringIO). I moduli che esportano un tot di funzioni hanno di solito nomi minuscoli.

Poiché i nomi di moduli corrispondono a nomi di file, e alcuni file system non sono sensibili a minuscole/maiuscole e troncano i nomi lunghi, è importante scegliere nomi di moduli relativamente corti e non in conflitto con altri nomi di moduli che differiscano solo per minuscole/maiuscole: non è un problema su Unix, ma può essere un problema quando il codice è trasportato su Mac o Windows.

La convenzione emergente è che un modulo di estensione scritto in C o C++ ha un modulo di accompagnamento in Python che offre un'interfaccia più ad alto livello (a es. più orientata agli oggetti): il nome del modulo Python è ParoCap, il modulo C o C++ è in minuscole e con una sottolineatura iniziale (ad esempio _socket).

I Package Python hanno generalmente un breve nome minuscolo.

Nomi di Classi

Quasi senza eccezione, i nomi di classe sono ParoCap. Le classi per uso interno hanno in addizione una sottolineatura iniziale.

Nomi di Eccezioni

Se un modulo definisce una singola classe di eccezioni sollevate in ogni tipo di condizioni, va chiamata "error" o "Error". I moduli built-in e di estensione usano "error" (ad es. os.error), i moduli Python usano "Error" (a es. xdrlib.Error).

Nomi di Funzioni

Le funzioni esportate da un modulo usano ParoCap o minuscole (o minuscole_con_sottolineature). Non vi è forte preferenza, ma ParoCap è usato per funzioni che offrono la funzionalità principale (ad es. nstools.WorldOpen), le minuscole sono più usare per funzioni tipo "utility") (ad es. pathhack.kos_root).

Nomi di Variabili Globali

(Speriamo ovviamente che queste variabili esistano solo per l'uso all'interno del modulo!) Le convenzioni sono simili a quelle per le funzioni esportate. I moduli progettati per essere usati con "from M import *" dovrebbero anteporre una sottolineatura a tutti i nomi delle loro variabili globali (così come a quelli di classi e funzioni interne) così da evitarne l'esportazione.

Nomi di metodi

La storia è molto simile a quella delle funzioni. Usa le minuscole per metodi usati da altre classi o funzioni che sono parte dell'implementazione di un tipo di oggetto. Usa una sottolineatura iniziale per metodi "interni" e variabili di istanza quando non c'è rischio di conflitto con attributi di sottoclassi o superclassi, o quando una sottoclasse potrebbe effettivamente avere bisogno di accedervi. Usa due sottolineature (nomi privati della classe, sin dai tempi di Python 1.4) nei casi in cui è importante che solo la classe corrente acceda a un suo attributo (renditi però conto che Python offre strumenti sufficienti a un utente insistente per ottenervi nondimeno accesso, a esempio attraverso l'attributo __dict__, a meno che tu non usi gli schemi di esecuzione ristretta, per esempio attraverso rexec e Bastion).

Riferimenti

Copyright

Questo documento è nel pubblico dominio.