Introduzione

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

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

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

Tabulazioni o spazi?

Lunghezza massima delle righe

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

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

• 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
  

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

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

Commenti in linea

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

    x = x+1 # Compensa per il bordo

Stringhe di documentazione

Burocrazie di versione

    __version__ = "$Revision: 1.3 $" 
    # $Source: /cvsroot/python/python/nondist/peps/pep-0008.txt,v $

Convenzioni sui nomi

Descrittivo: Stili dei Nomi

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!)

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

• PEP 7, Style Guide for C Code, van Rossum
• PEP 257, Docstring Conventions, Goodger, van Rossum
• http://www.python.org/doc/essays/styleguide.html

Copyright