Introducción al estilo de codificación Python

    Python como lenguaje de programación es bastante simple y compacto. En comparación con otros lenguajes, solo tiene un número relativamente bajo de palabras clave para internalizar para escribir código Python adecuado. Además, se prefiere tanto la simplicidad como la legibilidad del código, que es de lo que se enorgullece Python. Para lograr ambos objetivos, es útil que siga las pautas específicas del idioma.

    Este artículo se centra en las pautas mencionadas anteriormente para escribir código válido que represente una forma de programación más Pythonic. Es una selección de pautas que se centra en el uso práctico.

    Zen de Python

    
        Beautiful is better than ugly.
        Explicit is better than implicit.
        Simple is better than complex.
        Complex is better than complicated.
        Flat is better than nested.
        Sparse is better than dense.
        Readability counts.
        Special cases aren't special enough to break the rules.
        Although practicality beats purity.
        Errors should never pass silently.
        Unless explicitly silenced.
        In the face of ambiguity, refuse the temptation to guess.
        There should be one-- and preferably only one --obvious way to do it.
        Although that way may not be obvious at first unless you're Dutch.
        Now is better than never.
        Although never is often better than right now.
        If the implementation is hard to explain, it's a bad idea.
        If the implementation is easy to explain, it may be a good idea.
        Namespaces are one honking great idea -- let's do more of those!
        --Tim Peters
    

    Directrices generales de programación

    Siguiendo el Zen de Python, la legibilidad del código cuenta. Para garantizar un código con el formato adecuado, el lenguaje Python tiene algunas pautas de programación descritas en PEP8, por ejemplo, sangría consistente, una longitud de línea específica, escribir una declaración por línea solamente y formular fragmentos de código de una manera bastante explícita que implícita. Explicaremos estas reglas a continuación paso a paso.

    Sangría

    Se requiere sangría para clases, funciones (o métodos), bucles, condiciones y listas. Puede usar tabuladores o espacios, pero no debe combinar ambos en el mismo guión. Para Python 3, los espacios son el método de sangría preferido y, más específicamente, se desean cuatro espacios. Como ejemplo, se recomienda definir una lista de una de estas dos formas de la siguiente manera:

    Escribir listas

    # version 1
    numbers = [
        1, 2, 3,
        4, 5, 6
        ]
    
    # version 2
    numbers = [
        1, 2, 3,
        4, 5, 6
    ]
    

    Como se señaló en PEP8, el corchete de cierre puede alinearse debajo del primer carácter que no sea un espacio en blanco de la última línea de la lista, como en la “versión 1”, o debajo del primer carácter de la línea que comienza la lista como en “versión 2”.

    El uso de espacios requiere que trabajemos con la misma cantidad de espacios por nivel de sangría. El siguiente ejemplo le muestra cómo no para escribir su código, que mezcla tabuladores y un número diferente de espacios en cada línea.

    Mal ejemplo

    def draw_point(x, y):
      """draws a point at position x,y"""
        
    	if (x > 0):
    	  set_point(x, y)
      return
    

    Para sangrar bloques de código correctamente, el siguiente ejemplo utiliza cuatro espacios por nivel de sangría, en consecuencia:

    Buen ejemplo

    def draw_point(x, y):
        """draws a point at position x,y"""
    
        if (x > 0):
            set_point(x, y)
        return
    

    Un estado de cuenta por línea

    El ejemplo anterior sigue otra regla importante con respecto a la escritura de código: use solo una declaración por línea. Aunque, el lenguaje Python le permite escribir varias declaraciones por línea que están separadas por un punto y coma de la siguiente manera:

    Malo

    print ("Berlin"); print ("Cape Town")
    
    if x == 1: print ("Amsterdam")
    

    Para mayor claridad, escriba el código así, en su lugar:

    Bueno

    print ("Berlin")
    print ("Cape Town")
    
    if x == 1:
        print ("Amsterdam")
    

    Esto también se refiere al uso de módulos de Python. Muchos ejemplos de programación muestran dos o más módulos que se importan en una sola línea de la siguiente manera:

    Mala práctica

    import sys, os
    

    Es mucho mejor importar un módulo por línea, en su lugar:

    Buena práctica

    import sys
    import os
    

    Colocar el import declaraciones al principio del archivo, después de la información de copyright y las cadenas de documentación. Además, es común agrupar las import declaraciones en módulos estándar de la biblioteca de Python, módulos de terceros relacionados y, finalmente, importaciones específicas de la biblioteca. Insertar una línea en blanco y comentarios ayudan a la legibilidad y a comprender mejor el código.

    Importación de módulos externos

    # use operating-system specific routines
    import os
    
    # use regular expressions routines
    import re
    
    # use SAX XML library/parser
    from xml.sax import make_parser, handler
    ...
    

    Longitud de la línea

    Una sola línea no debe exceder la cantidad de 79 caracteres, mientras que una cadena de documentos o un comentario no debe tener más de 72 caracteres. Las líneas de código se pueden ajustar usando una barra invertida () como sigue:

    Código con salto de línea

    with open('/path/to/some/file/you/want/to/read') as file_1, 
         open('/path/to/some/file/being/written', 'w') as file_2:
        file_2.write(file_1.read())
    

    Código explícito vs implícito

    Python como lenguaje de secuencias de comandos es lo suficientemente flexible como para permitirle utilizar “trucos” en todo el código. Aunque debes tener en cuenta que muchas veces tu código es leído por otros desarrolladores. Para mejorar la legibilidad, es mejor escribir código explícito en lugar de hacer suposiciones implícitas, como usar frases breves o “trucos”.

    En el siguiente ejemplo, la función calculation() oculta los dos valores x y y en un solo parámetro llamado args. Esta forma de escritura también permite a las personas que llaman pasar más o menos que estos valores a la función si lo desean, pero no es obvio a primera vista.

    Malo

    def calculation(*args):
        """calculation of the total"""
    
        x, y = args
        return (x+y)
    
    print(calculation(3, 4))
    

    Para mayor claridad, se recomienda escribirlo así, en su lugar:

    Bueno

    def calculation(x,y):
        """calculation of the total"""
    
        total = x + y
        return (total)
    
    print(calculation(3, 4))
    

    Convenciones de nombres

    Existen bastantes variaciones para nombrar módulos, clases, métodos / funciones y variables. Esto incluye el uso de letras minúsculas y mayúsculas con o sin guiones bajos, palabras en mayúscula y estilos mixtos. Debido a la gran diversidad de desarrolladores, encontrará todos estos estilos y hay poca coherencia entre los módulos.

    Variaciones de estilo de nomenclatura

    shoppingcart = []  # lowercase
    shopping_cart = [] # lowercase with underscores
    SHOPPINGCART = []  # uppercase
    SHOPPING_CART = [] # uppercase with underscores
    ShoppingCart = []  # capitalized words
    shoppingCart = []  # mixed style
    

    Depende de usted cuál de los estilos utilice. Nuevamente, sea consistente y use el mismo estilo en todo su código. Según PEP8, se aplican las siguientes reglas principales:

    • Los nombres de los identificadores deben ser compatibles con ASCII
    • Se requiere que los módulos tengan nombres cortos en minúsculas
    • Las clases siguen la convención de palabras en mayúscula
    • Las excepciones siguen la convención de palabras en mayúscula y se espera que tengan la Error sufijo si se refieren a errores
    • Las constantes se escriben en mayúsculas

    Para obtener más detalles, consulte el estándar PEP8.

    También debemos señalar que se considera más “Pythonic” usar el enfoque de “minúsculas con guiones bajos” al nombrar variables en Python, aunque se permite cualquier enfoque.

    Validación de estilo de código

    Las pautas son excelentes para lograr un código que siga ciertas condiciones. Como programador, debe asegurarse de seguirlos tanto como sea posible. Las herramientas automatizadas son excelentes para ayudarlo a validar su código.

    Como se mencionó anteriormente, las pautas se describen en PEP8. En consecuencia, el lenguaje Python contiene una herramienta de línea de comandos correspondiente para ayudarlo a verificar su código según las pautas. Originalmente conocido como pep8, se cambió el nombre de este verificador de código a pycodestyle en 2016. Es mantenido por la Autoridad de Calidad del Código de Python y pertenece a una serie de herramientas como los analizadores de código fuente pilón y copos, el verificador de complejidad McCbe así como el verificador de cadenas de documentos pydocstyle.

    pycodestyle analiza su código Python e informa violaciones que cubren errores de sangría, líneas en blanco innecesarias y el uso de tabuladores en lugar de espacios. El siguiente ejemplo contiene una salida de muestra con algunos errores y advertencias típicos:

    $ pycodestyle --first stack.py
    stack.py:3:1: E265 block comment should start with "https://Pharos.sh.com/introduction-to-the-python-coding-style/#"
    stack.py:12:1: E302 expected 2 blank lines, found 1
    stack.py:13:1: W191 indentation contains tabs
    

    En Debian GNU / Linux, la herramienta está disponible como paquetes python-pycodestyle (para Python 2.x) y python3-pycodestyle (para Python 3.x). Ambos vienen con una serie de parámetros útiles, por ejemplo:

    • --first: Muestra la primera aparición de cada error (como se ve arriba). La salida muestra el archivo en el que se detectó el error, así como el número de línea y la columna.
    • --show-source: Muestra el código fuente de cada error
    $ pycodestyle --show-source stack.py
    stack.py:3:1: E265 block comment should start with "https://Pharos.sh.com/introduction-to-the-python-coding-style/#"
    #o
    ^
    stack.py:12:1: E302 expected 2 blank lines, found 1
    class Stack:
    ^
    stack.py:13:1: W191 indentation contains tabs
        def __init__(self):
    ^
    ...
    
    • --statistics: Cuente errores y advertencias. En el siguiente ejemplo, pycodestyle detectó dos errores, E265 y E302, así como 30 advertencias (W191).
    $ pycodestyle --statistics stack.py
    ...
    1       E265 block comment should start with "https://Pharos.sh.com/introduction-to-the-python-coding-style/#"
    1       E302 expected 2 blank lines, found 1
    30      W191 indentation contains tabs
    

    La misma herramienta también es disponible en linea. Simplemente copie y pegue su código en la herramienta y vea el resultado de la validación.

    Conclusión

    Escribir código Python adecuado no siempre es fácil. Pero, afortunadamente, existen pautas que ayudan, así como herramientas de línea de comandos para garantizar que su código cumpla con estas pautas. Con los diversos recursos disponibles, puede ser muy fácil 🙂

    Etiquetas:

    Deja una respuesta

    Tu dirección de correo electrónico no será publicada. Los campos obligatorios están marcados con *