Leggibilità del codice Python

Question

Ho un'esperienza di programmazione con lingue tipizzate staticamente. Ora scrivendo il codice in Python mi sento in difficoltà con la sua leggibilità. Diciamo che ho una classe Host:

class Host(object): 
    def __init__(self, name, network_interface): 
    self.name = name 
    self.network_interface = network_interface 

Non capisco da questa definizione, ciò che "network_interface" dovrebbe essere. È una stringa , ad esempio "eth0" o è un'istanza di una classe NetworkInterface? L'unico modo in cui sto pensando di risolvere questo è documentare il codice con una "docstring". Qualcosa del genere:

class Host(object): 
    ''' Attributes: 
     @name: a string 
     @network_interface: an instance of class NetworkInterface''' 

Oppure ci sono convenzioni di nome per cose del genere?

Answer 1

L'utilizzo di linguaggi dinamici ti insegnerà qualcosa sui linguaggi statici: tutto l'aiuto che hai ottenuto dal linguaggio statico che ora ti manca nel linguaggio dinamico non è stato di grande aiuto.

Per utilizzare l'esempio, in un linguaggio statico, si dovrebbe sapere che il parametro era una stringa e in Python no. Quindi in Python scrivi una docstring.E mentre lo stai scrivendo, ti rendi conto che avevi più da dire su di esso che "è una stringa". Devi dire quali dati sono nella stringa e quale formato dovrebbe avere, e quale è l'impostazione predefinita, e qualcosa sulle condizioni di errore.

E poi ti rendi conto che avresti dovuto scrivere tutto questo anche per il tuo linguaggio statico. Certo, Java ti costringerebbe a sapere che si trattava di una stringa, ma ci sono tutti questi altri dettagli che devono essere specificati, e devi farlo manualmente in qualsiasi lingua.

Answer 2

Le convenzioni di docstring sono PEP 257.

L'esempio ci segue questo formato per argomenti che specificano, è possibile aggiungere i tipi se ne importa:

def complex(real=0.0, imag=0.0): 
    """Form a complex number. 

    Keyword arguments: 
    real -- the real part (default 0.0) 
    imag -- the imaginary part (default 0.0) 

    """ 
    if imag == 0.0 and real == 0.0: return complex_zero 
    ... 

C'era anche un PEP rifiutata per docstrings per gli attributi (piuttosto che argomenti del costruttore).

Answer 3

La soluzione più pitonica è quella di documentare con esempi. Se possibile, indicare le operazioni che un oggetto deve supportare per essere accettabile, piuttosto che un tipo specifico.

class Host(object): 
    def __init__(self, name, network_interface) 
    """Initialise host with given name and network_interface. 

    network_interface -- must support the same operations as NetworkInterface 

    >>> network_interface = NetworkInterface() 
    >>> host = Host("my_host", network_interface) 

    """ 
    ... 

A questo punto, collegare il vostro sorgente fino a doctest per assicurarsi che i vostri esempi doc continuare a lavorare in futuro.

Answer 4

Personalmente ho trovato molto utile usare pylint per convalidare il mio codice.

Se segui il suggerimento di pylint in modo quasi automatico, il tuo codice diventa più leggibile, migliorerai le tue abilità di scrittura in Python, rispetti le convenzioni di denominazione. Puoi anche definire le tue convenzioni di denominazione e così via. È molto utile specialmente per un principiante pitone.

Ti suggerisco di usare.

Answer 5

Python, sebbene non sia scritto in modo esplicito come C o Java, è ancora digitato e genera eccezioni se si stanno facendo cose con tipi che semplicemente non suonano bene insieme.

A tal fine, se si è preoccupati che il proprio codice venga utilizzato correttamente, mantenuto correttamente, ecc. È sufficiente utilizzare docstring, commenti o nomi di variabili ancora più espliciti per indicare quale dovrebbe essere il tipo.

Ancora meglio, includere il codice che consentirà di gestire qualsiasi tipo possa essere passato fino a quando produce un risultato utilizzabile.

Answer 6

Un vantaggio della digitazione statica è che i tipi sono una forma di documentazione. Quando si programma in Python, è possibile documentare in modo più flessibile e scorrevole. Naturalmente nel tuo esempio vuoi dire che network_interface dovrebbe implementare NetworkInterface, ma in molti casi il tipo è ovvio dal contesto, dal nome della variabile o dalla convenzione, e in questi casi omettendo l'ovvio puoi produrre codice più leggibile. Comune è descrivere il significato di un parametro e dare implicitamente il tipo.

Ad esempio:

def Bar(foo, count): 
    """Bar the foo the given number of times.""" 
    ... 

Questa descrive la funzione conciso e preciso. Quello che foo e bar significano sarà ovvio dal contesto, e quel conteggio è un intero (positivo) implicito.

Per esempio, ho appena citato il tipo nella stringa di documento:

"""Create a named host on the given NetworkInterface.""" 

Questo è più breve, più leggibile, e contiene ulteriori informazioni rispetto a un elenco dei tipi.