6 buenas prácticas de Python para escribir mejor código

Buenas prácticas en Python 

1. Buenas prácticas de Python para la calidad del código

Escribir código legible y ordenado marca la diferencia y puede impulsar tu carrera profesional. Aunque para quienes empiezan programar pueda parecer un proceso mecánico y complejo, la realidad es que programar es un arte. 

Hay muchos consejos que puedes seguir para aumentar la calidad del código en Python. Aquí tienes algunos de los más relevantes.

La tiranía de la indentación

La indentación son los espacios al inicio de una línea de código. Mientras que en otros lenguajes es solo un recurso para la legibilidad, en Python es obligatoria. Python usa la indentación para abrir un bloque de código. Concretamente, 4 espacios consecutivos por nivel de indentación, como se muestra en el siguiente código:

for number in [1,2,3,4]:
    if number % 2 == 0:
        print(number)
    else:
        continue

Longitud máxima de línea

PEP 8 recomienda que ninguna línea supere los 79 caracteres. Tiene sentido: las líneas cortas se leen mejor. Además, esta longitud permite tener varios archivos abiertos uno junto a otro.

Líneas en blanco

Rodea con dos líneas en blanco las definiciones de funciones y clases de nivel superior. Dentro de una clase, deja una línea en blanco alrededor de cada método. Puedes usar líneas en blanco adicionales (con moderación) para separar grupos de funciones relacionadas. Por último, usa líneas en blanco dentro de las funciones (también con moderación) para indicar secciones lógicas. 

Usa linters y autoformateadores

Dominar el código lleva tiempo. Estar pendiente de todos los detalles mientras programas puede ser un reto y llevarte muchas horas. Por suerte, las máquinas, en particular los linters y los formateadores, pueden ayudarnos a garantizar la calidad del código. 

Los linters realizan análisis estático del código fuente y buscan discrepancias semánticas. Los formateadores son herramientas similares que reestructuran espacios, longitud de línea, colocación de argumentos, etc., para que tu código tenga un aspecto coherente en distintos archivos o proyectos. Python te ofrece un buen abanico de linters y formateadores entre los que elegir.

Ten presentes los principios

Aunque algunas de las reglas anteriores son directas, programar a menudo tiene que ver con el buen gusto y la intuición. Para convertirte en un artista del código, conviene conocer algunos de los principios que sustentan Python. Un gran ejemplo es el Zen de Python, que tratamos en otro artículo.  

2. Buenas prácticas de logging en Python

El logging es un medio para seguir los eventos que ocurren cuando se ejecuta un software. Especialmente cuando las aplicaciones crecen en tamaño y complejidad, el logging se vuelve crítico para desarrollar, depurar, ejecutar y hacer seguimiento del rendimiento.  

El módulo logging forma parte de la biblioteca estándar de Python desde la versión 2.3 para dar soporte a las prácticas de registro y está descrito en detalle en PEP 282.

El logging se asemeja en espíritu a la función print. Sin embargo, print carece de mucha información útil para un desarrollador. Con logging puedes registrar marcas de tiempo y el número de línea en el que se produjo el error. También puedes enviar errores o cualquier información a archivos, sockets, etc.

Para importar el módulo, basta con ejecutar este código:

import logging

No todos los mensajes de log son iguales. De hecho, el módulo define una serie de niveles según la gravedad del mensaje. Son los siguientes:

• NOTSET (0): significa que se registrarán todos los mensajes.
• Debug (10): útil para diagnosticar problemas en el código. 
• Info (20): puede usarse para confirmar que no hay fallos en el código. Un buen caso de uso a nivel info es seguir el progreso del entrenamiento de un modelo de machine learning. 
• Warning (30): indica un problema que podría ocurrir en el futuro. Por ejemplo, un aviso por un módulo que podría quedar obsoleto o por poca memoria RAM. 
• Error (40): un fallo serio en el código; puede ser un error de sintaxis, falta de memoria o excepciones. 
• Critical (50): un error por el que el programa podría dejar de funcionar o cerrarse de forma abrupta.

import logging
logging.info('This message is just informative')
logging.debug('My missions is to provide information about debugging.')
logging.critical("A Critical Logging Message")

Dicho esto, a continuación tienes una lista de seis buenas prácticas para gestionar el logging en Python.  

Usa logs en lugar de prints

Hemos dicho que los logs proporcionan información en la misma línea que las funciones print. Sin embargo, los logs son mucho más potentes y pueden aportar información más granular. 

Puede ser tentador tirar de print, sobre todo si no dominas las rutinas de logging, pero los logs siempre serán la opción más segura. Escalan mejor y se adaptan a aplicaciones complejas. 

La web está llena de guías y documentación. Por ejemplo, este tutorial de logging de DataCamp puede ser justo lo que necesitas para empezar.

Usa el módulo logging 

Este módulo es la opción de referencia para la mayoría de desarrolladores de Python. Esto significa que está bien mantenido y respaldado por una gran comunidad que siempre tendrá respuesta a tus dudas.

Elige bien el nivel de logging

El módulo de logging trae seis niveles de mensajes. Cada uno está pensado para un propósito específico. Cuanto más te ciñas a ellos, más fácil será para ti y para quienes usen tu código entender qué está pasando.

Incluye marcas de tiempo en los logs

Es una característica clave de los logs que las funciones print no tienen. Además de saber dónde apareció un problema, es importante saber cuándo ocurrió. Las marcas de tiempo son tus mejores aliadas en estas situaciones. Asegúrate de usar el formato estándar ISO 8601.

Vacía la papelera de logs

Usa clases RotatingFileHandler, como TimedRotatingFileHandler, en lugar de FileHandler, para archivar, comprimir o eliminar logs antiguos y evitar problemas de espacio. Estas clases liberan espacio cuando se alcanza un límite de tamaño o se cumple una condición temporal.

3. Buenas prácticas de comentarios en Python

Los comentarios son muy importantes para dejar anotaciones a futuras personas lectoras de nuestro código. Aunque es difícil definir cómo se debe comentar, sí hay ciertas pautas que podemos seguir: 

• Cualquier comentario que contradiga al código es peor que no comentar. Por eso es clave actualizar código y comentarios para evitar incoherencias. 
• Los comentarios deben ser oraciones completas, con la primera letra en mayúscula. 
• Intenta escribir los comentarios en inglés. Aunque cada cual es libre de elegir el idioma, se recomienda hacerlo en inglés. 
• Asegúrate de que tus comentarios sean claros y fáciles de entender para otras personas que hablen el idioma en el que escribes.

Hay dos tipos de comentarios: comentarios de bloque y comentarios en línea. 

Un comentario de bloque explica el código que le sigue. Normalmente se indenta al mismo nivel que el bloque de código. Cada línea de un comentario de bloque empieza con # y un espacio, así:

# This is a block comment
print('Welcome to DataCamp!")

Por su parte, los comentarios en línea aparecen en la misma línea que el código. Deben separarse al menos con dos espacios de la sentencia. Al igual que un comentario de bloque, empiezan con una almohadilla (#), seguida de un espacio y el texto. 

print ("Have you ever tried Python?") # This is an inline comment

4. Buenas prácticas de docstrings en Python

Un docstring es una cadena literal que aparece como la primera sentencia en la definición de un módulo, función, clase o método. Suele usarse para generar automáticamente la documentación del código. Por ello, un docstring puede consultarse en tiempo de ejecución mediante el atributo especial obj.__doc__ del objeto.

Por coherencia, los docstrings se encierran siempre entre triples comillas dobles (""").

Hay dos formas de docstrings: de una sola línea y multilínea. Los de una sola línea son para casos realmente obvios. Deben caber en una línea. El siguiente ejemplo ilustra un docstring de una línea en la función multiply():

def multiply(x, y):
    """ Return the product of two numbers """
    result = x * y
    return result

Por otro lado, un docstring multilínea puede abarcar varias líneas. Debe documentar la función del script, la sintaxis de la línea de comandos, las variables de entorno y los archivos. Los mensajes de uso pueden ser bastante elaborados y deben bastar para que una persona sin experiencia use el comando correctamente.

def calculate_salary(hours, price=20):
    """ Return the salary according to the hours worked

    Arguments:
    hours: total hours investe
    price: price of each hours worked. Minimum price is 20 dollars
    """
    salary = hours * price
    return salary

Puedes encontrar una explicación más detallada de los docstrings en PEP257.

5. Buenas prácticas de documentación en Python

Mientras que los comentarios ayudan a que otras personas desarrolladoras con las que trabajas entiendan tu código, la documentación tiene como objetivo ayudar a una comunidad de usuarios potenciales a aprender a usar tu software. Es un paso crítico: por muy bueno que sea tu software, si la documentación no es suficiente, o peor aún, no existe, la gente no lo usará. 

Incluir un archivo README siempre es una buena práctica, sobre todo si trabajas en un proyecto nuevo. Estos archivos suelen ser el punto de entrada principal para quienes leen tu código e incluyen información general tanto para usuarios como para personas mantenedoras del proyecto. 

Aunque conciso, el archivo README debería explicar el propósito del proyecto, la URL de la fuente principal del software y el apartado de créditos.

Igualmente, deberías incluir siempre un archivo setup.py para garantizar que el software o la librería se empaqueta y distribuye con Distutils, el estándar para distribuir módulos de Python.

Además, si tu software requiere otras dependencias o paquetes para ejecutarse, deberías incluir un archivo requirements.txt que describa las dependencias necesarias y sus versiones.

Por último, eres libre de añadir cualquier otra información que consideres relevante para potenciales usuarios. Por ejemplo, es buena práctica ofrecer ejemplos de cómo funciona tu paquete o tus funciones. 

6. Buenas prácticas con entornos virtuales en Python 

Para asegurar orden y coherencia en tus proyectos de datos, es buena práctica crear un entorno virtual para cada proyecto nuevo. 

Los entornos virtuales, también llamados virtualenvs, ayudan a desacoplar y aislar versiones de Python y de las librerías que requiere tu proyecto y sus versiones de pip asociadas. Esto permite a los usuarios finales instalar y gestionar su propio conjunto de software y versiones de forma independiente a las del sistema. 

Para crear virtualenvs, primero debemos instalar el paquete necesario, escribiendo la siguiente línea en tu terminal:

pip install virtualenv

Para crear un nuevo virtualenv, este comando hará la magia. Llamaremos al nuevo entorno virtual “new_venv”

python3 -m venv /path/to/new/virtual/environment/new_venv

Convenciones de nombres en Python

Uno de los errores más comunes entre quienes empiezan con Python es nombrar mal variables, clases, funciones, etc. Las convenciones de nombres son elementos clave para garantizar la legibilidad del código.

PEP 8 explica la forma estándar de nombrar objetos en Python. Según estas directrices, los módulos y paquetes nuevos (incluidos frameworks de terceros) deberían ceñirse a estos estándares, pero si una biblioteca existente utiliza otro estilo, se prioriza la coherencia interna.

Evita usar nombres demasiado genéricos o ambiguos. Además, los identificadores usados en la biblioteca estándar deben ser compatibles con ASCII, tal y como se describe en PEP 3131.

# Malos nombres:
data_structure, ríos_españa, dictionary_with_countries_and_capitals
# Buenos nombres:
user_profile, stop_words, global_emissions_df

A continuación tienes una lista de las convenciones de nombres para los objetos más comunes en Python.

• Paquetes y módulos
• Los nombres de paquetes y módulos deben ir en minúsculas
• Solo usa guiones bajos si mejoran la legibilidad.
• Clases
• Los nombres de clase deben seguir la convención UpperCaseCamelCase
• Las clases integradas de Python, sin embargo, suelen ser palabras en minúsculas
• Variables de instancia, métodos y funciones
• Los nombres de variables de instancia deben ir en minúsculas
• Usa guiones bajos para separar palabras en los nombres de variables
• Las variables de instancia no públicas deben comenzar con un guion bajo
• Constantes
• Los nombres de constantes deben ir completamente en mayúsculas
• Usa guiones bajos para separar palabras en las constantes

Conclusión

Dominar las buenas prácticas de Python es esencial para escribir código limpio, eficiente y fácil de mantener. Si sigues las directrices sobre calidad de código, logging, comentarios y documentación, y usas herramientas como los entornos virtuales, tus proyectos serán más fáciles de gestionar, colaborar y escalar.

A medida que sigas mejorando tus habilidades en Python, plantéate explorar recursos de aprendizaje más profundos para afianzar tu comprensión del lenguaje y su amplio abanico de aplicaciones. Si buscas una guía estructurada, echa un vistazo a estos recursos:

• How to Learn Python: A Guide to Becoming an Expert – Esta guía experta te ayudará a planificar tu aprendizaje con trucos y técnicas para dominar Python.
• Introduction to Python for Developers – Perfecto para desarrolladores que quieren empezar con Python, este curso cubre los conceptos y funcionalidades clave del lenguaje de forma práctica.
• Introduction to Data Science in Python – Cuando te sientas cómodo con Python, adéntrate en la ciencia de datos con este curso para principiantes. Cubre librerías y técnicas esenciales para trabajar con datos en Python.