Introducción al estilo de codificación de Python

Python como lenguaje de secuencias de comandos es bastante simple y compacto. En comparación con otros idiomas, solo tiene un número relativamente bajo de palabras clave para internalizar para...

Python como lenguaje de secuencias de comandos es bastante simple y compacto. En comparación con otros lenguajes, solo tiene una cantidad relativamente baja de palabras clave para internalizar para escribir el código de Python adecuado. Además, se prefiere tanto la simplicidad como la legibilidad del código, que es de lo que Python se enorgullece. 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 pythonica. Es una selección de pautas que se enfoca en el uso práctico, y se pueden leer más pautas en La guía del autoestopista de Python y la Guía de estilo PEP8.

Tim Peters, un desarrollador estadounidense de Python, combina los principios del lenguaje con humor en Zen of Python. Estas reglas forman parte de los principales objetivos y estilos del lenguaje. Con suerte, estas reglas te ayudarán a orientarte como desarrollador.

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 {#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 piezas de código de una manera más explícita que implícita. Explicaremos estas reglas a continuación paso a paso.

sangría

La sangría es necesaria para clases, funciones (o métodos), bucles, condiciones y listas. Puede usar tabuladores o espacios, pero no debe combinarlos 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 en una de estas dos formas de la siguiente manera:

Listas de escritura

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
# 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 paréntesis de cierre se puede alinear bajo el primer carácter que no sea un espacio en blanco de la última línea de la lista, como en "versión 1", o bajo el primer carácter de la línea que inicia 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 escribir su código, que combina tabuladores y una cantidad diferente de espacios en cada línea.

Mal ejemplo

1
2
3
4
5
6
def draw_point(x, y):
  """draws a point at position x,y"""
    
    if (x > 0):
      set_point(x, y)
  return

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

Buen ejemplo

1
2
3
4
5
6
def draw_point(x, y):
    """draws a point at position x,y"""

    if (x > 0):
        set_point(x, y)
    return

Una declaración 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

1
2
3
print ("Berlin"); print ("Cape Town")

if x == 1: print ("Amsterdam")

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

Bueno

1
2
3
4
5
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

1
import sys, os

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

Buena práctica

1
2
import sys
import os

Coloque las declaraciones de importación al principio del archivo, después de la información de derechos de autor y las cadenas de documentación. Además, es común agrupar las declaraciones de importación 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 así como comentarios ayudan a la legibilidad y a comprender mejor el código.

Importación de módulos externos

1
2
3
4
5
6
7
8
9
# 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 línea

Una sola línea no debe exceder el número de 79 caracteres, mientras que una cadena de documentación o comentario no debe exceder los 72 caracteres. Las líneas de código se pueden envolver usando una barra invertida (\) de la siguiente manera:

Código con un salto de línea

1
2
3
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 frente a código implícito

Python como lenguaje de secuencias de comandos es lo suficientemente flexible como para permitirle usar "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 ingeniosas o "trucos".

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

Malo

1
2
3
4
5
6
7
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

1
2
3
4
5
6
7
def calculation(x,y):
    """calculation of the total"""

    total = x + y
    return (total)

print(calculation(3, 4))

Convenciones de nomenclatura {#convenciones de nomenclatura}

Existen bastantes variaciones para nombrar módulos, clases, métodos/funciones y variables. Esto incluye el uso de letras mayúsculas y minúsculas con o sin guiones bajos, palabras en mayúsculas 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 nombres

1
2
3
4
5
6
shoppingcart = []  # lowercase
shopping_cart = [] # lowercase with underscores
SHOPPINGCART = []  # uppercase
SHOPPING_CART = [] # uppercase with underscores
ShoppingCart = []  # capitalized words
shoppingCart = []  # mixed style

Cuál de los estilos que uses depende de ti. Nuevamente, sea consistente y use el mismo estilo en todo su código. De acuerdo con PEP8, se aplican las siguientes reglas principales:

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

Para obtener más detalles, eche un vistazo al estándar PEP8.

También debemos señalar que se considera más "Pythonic" usar el enfoque "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, desea 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 comando correspondiente para ayudarlo a verificar su código con las pautas. Originalmente conocido como pep8, este verificador de código pasó a llamarse pycodestyle en 2016. Lo mantiene la Autoridad de calidad de código de Python y pertenece a una serie de herramientas como la analizadores de código fuente pilinto y hojuelas, el verificador de complejidad [mccabe](http://pypi.python .org/pypi/mccabe), así como el comprobador de cadenas de documentos pydocstyle.

pycodestyle analiza su código Python e informa violaciones que cubren errores de sangría, líneas en blanco que son 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:

1
2
3
4
$ pycodestyle --first stack.py
stack.py:3:1: E265 block comment should start with '# '
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 ocurrencia de cada error (como se ve arriba). El resultado 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
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
$ pycodestyle --show-source stack.py
stack.py:3:1: E265 block comment should start with '# '
#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: Cuenta errores y advertencias. En el siguiente ejemplo, pycodestyle detectó dos errores, E265 y E302, así como 30 advertencias (W191).
1
2
3
4
5
$ pycodestyle --statistics stack.py
...
1       E265 block comment should start with '# '
1       E302 expected 2 blank lines, found 1
30      W191 indentation contains tabs

La misma herramienta también está disponible en línea. Simplemente copie y pegue su código en la herramienta y vea el resultado de la validación.

pep8online.com validation result{.img-responsive}

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

Agradecimientos

El autor quisiera agradecer a Zoleka Hatitongwe por su apoyo mientras preparaba el artículo.

Licensed under CC BY-NC-SA 4.0