Lectibilidad de código de Python

Question

Tengo una experiencia de programación con lenguajes tipados estáticamente. Ahora, escribiendo código en Python, siento dificultades con su legibilidad. Digamos que tengo una clase Anfitrión:

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

No entiendo de esta definición, lo que "network_interface" debe ser. ¿Es una cadena , como "eth0" o es una instancia de una clase NetworkInterface? La única forma en que estoy pensando en resolver esto es documentando el código con un "docstring". Algo como esto:

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

O tal vez hay convenciones de nombres para cosas como esas?

Answer 1

El uso de lenguajes dinámicos le enseñará algo acerca de los lenguajes estáticos: toda la ayuda que obtuvo del lenguaje estático que ahora extrañe en el lenguaje dinámico, no fue del todo útil.

Para utilizar su ejemplo, en un lenguaje estático, sabría que el parámetro era una cadena, y en Python no. Entonces en Python escribes una docstring.Y mientras lo estás escribiendo, te das cuenta de que tienes más para decir al respecto que, "es una cadena". Debe indicar qué datos hay en la cadena, y qué formato debería tener, y cuál es el valor predeterminado, y algo sobre las condiciones de error.

Y luego se da cuenta de que debería haber escrito todo eso para su lenguaje estático también. Claro, Java te obligaría a saber que era una cadena, pero hay todos estos otros detalles que deben especificarse, y tienes que hacerlo manualmente en cualquier idioma.

Answer 2

Las convenciones de docstring están en PEP 257.

El ejemplo no sigue este formato para que especifican argumentos, puede agregar los tipos si son importantes:

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 
    ... 

Hubo también una PEP rechazado por cadenas de documentación para los atributos (en lugar de argumentos del constructor).

Answer 3

La solución más pitonica es documentar con ejemplos. Si es posible, indique qué operaciones debe admitir un objeto para que sean aceptables, en lugar de un tipo específico.

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) 

    """ 
    ... 

En este punto, conectar su fuente hasta doctest para asegurarse de que sus ejemplos doc continúan trabajando en el futuro.

Answer 4

Personalmente, me pareció muy útil usar pylint para validar mi código.

Si sigue la sugerencia de la tableta casi automáticamente su código se vuelve más legible, mejorará sus habilidades de escritura en python, respetará las convenciones de nomenclatura. También puede definir sus propias convenciones de nomenclatura, etc. Es muy útil especialmente para un principiante de Python.

Le sugiero que utilice.

Answer 5

Python, aunque no está escrito tan abiertamente como C o Java, todavía se escribe y arrojará excepciones si está haciendo cosas con tipos que simplemente no funcionan bien juntos.

Para este fin, si le preocupa que su código se use correctamente, se mantenga correctamente, etc. simplemente use docstrings, comentarios o incluso nombres de variables más explícitos para indicar cuál debe ser el tipo.

Aún mejor, incluya un código que le permita manejar cualquier tipo que se pueda pasar, siempre que produzca un resultado utilizable.

Answer 6

Uno de los beneficios del tipado estático es que los tipos son una forma de documentación. Al programar en Python, puede documentar de manera más flexible y fluida. Por supuesto, en su ejemplo, quiere decir que network_interface debe implementar NetworkInterface, pero en muchos casos el tipo es obvio por el contexto, el nombre de la variable o por convención, y en estos casos, al omitir lo obvio, puede producir un código más legible. Común es describir el significado de un parámetro e implícitamente dar el tipo.

Por ejemplo:

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

Esto describe la función concisamente y precisa. Lo que significan foo y bar será obvio desde el contexto, y ese recuento es un entero (positivo) está implícito.

Para su ejemplo, que acababa de mencionar el tipo en la cadena de documento:

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

Esto es más corto, más fácil de leer, y contiene más información que una lista de los tipos.