En nuestro último artículo, hablamos de la guía de estilo PEP 8 de Python, mencionando que su principal objetivo es mejorar la legibilidad del código. Un código se escribe una vez, y se revisa muchas a lo largo del tiempo, por lo que optimizar la capacidad de lectura del mismo se vuelve importante.
El día de hoy, haremos foco en aplicaciones específicas de la guía de estilo, a través de casos concretos, para que puedas aplicarlo en tu código ahora mismo, y dispongas de una guía práctica en el futuro (aunque verás que resulta sencillo de asimilar).
Nombres de variables - Convenciones
Un nombre de variable descriptivo y bien escogido te evita tener que recurrir a la memoria a medida que el código se va haciendo más extenso y complejo, ya que con solo leerla tendrás una idea de la información que esperas encontrar en la misma. Elegir un nombre de variable "x" para almacenar el nombre completo de una persona no genera el ahorro de tiempo esperado, ya que muy probablemente necesitemos ir y volver sobre el código para recordar su significado.
De hecho, nombres formados por una sola letra son por lo general malas prácticas, sobre todo si dichas letras son l (L minúscula), O (mayúscula o minúscula), I (i mayúscula), dado que pueden confundirse con números en el editor de texto, haciendo difícil su interpretación, sumado al hecho que dichos nombres en sí no aportan información respecto de su contenido (salvo justificables excepciones, como por ejemplo ciertas funciones matemáticas o constantes en fórmulas).
Para la mayoría de los casos (funciones, variables, métodos y nombres de módulos), la convención sugiere utilizar una o más palabras completamente en minúsculas, de ser necesario separando las mismas con un guion bajo si se trata de nombres de más de una palabra (mi_variable). Para el caso de nombres de paquetes aplica casi el mismo criterio, a diferencia que la convención nos sugiere no emplear guiones bajos para separar diferentes palabras, sino escribirlas juntas (mipaquete). Para el caso de las clases, la costumbre es utilizar el estilo conocido como "camel case" (colocando cada palabra con mayúscula inicial y sin espacio entre ellas, como por ejemplo MiClase). Constantes, emplean una convención de nombrado totalmente en mayúsculas, separando las palabras con guiones bajos (MI_VARIABLE).
Organización del Código
Líneas en Blanco
La manera en la que el código se distribuye en el editor es otro aspecto que tiene un gran impacto en la legibilidad del mismo. Necesitamos "oxigenar" el código generando espacios horizontales (líneas en blanco) y verticales (indentación), para reconocer estructuras y separarlas rápidamente. Lo contrario a esto es un código denso, extenso y compacto. Desde luego, la idea no es exagerar: sumar más espacios de los necesarios representará un incremento en el "tamaño" del código (cuánta superficie ocupa en el editor, o cuánto tendrás que scrollear para llegar de un punto a otro).
La convención sugiere utilizar dos líneas en blanco para separar funciones y clases principales (generales a nivel del módulo), y una línea en blanco para separar los métodos dentro de una misma clase. Dentro de una misma función, se recomienda utilizar una línea en blanco por cada paso principal completado y antes de return (un paso principal abarca varias líneas de código para generar un resultado intermedio que se utilice a continuación).
class MiPrimeraClase:
pass
class MiSegundaClase:
def mi_primer_metodo(self):
return None
def mi_segundo_metodo(self):
#paso 1
#paso 2
#paso 3
#resultado intermedio
#paso 4
#paso 5
return None
def mi_funcion_general():
return None
Indentación
Por otro lado, la indentación es tan importante en Python que de hecho es obligatoria, y devuelve errores si no se respeta. La indentación ayuda a organizar y jerarquizar bloques de código para reconocer sencillamente a dónde pertenece cada línea. Ahora, con respecto a cómo implementar la indentación, la guía de estilo PEP 8 nos sugiere utilizar cuatro espacios consecutivos, en lugar de tabular. Varios IDEs permiten configurar el comportamiento de Tab tal que introduzca cuatro espacios en lugar de una tabulación, para implementarlo rápidamente.
Largo de Línea
Finalmente, en cuanto a la extensión en caracteres de cada línea de código, PEP 8 nos sugiere utilizar como máximo 79 caracteres por línea. Esta es una buena solución de compromiso entre cantidad de texto y adaptabilidad a varios tamaños de ventana, sin que el código se "envuelva" a sí mismo, ajustándose para ocupar más renglones. Si utilizas un IDE como PyCharm, no tendrás que preocuparte de contar caracteres ya que la sugerencia se mostrará si te excedes.
Saltos de línea
Si tu línea de código necesitará de más de 79 caracteres para completarse, se recomiendan distintas estrategias para hacerlo:
1. Alinear los bloques de parámetros con su paréntesis de apertura cuando ocurre un salto de línea.
2. Añadir una indentación extra cuando la línea siguiente también tiene una indentación, para separar claramente los los bloques de código, o añadir un comentario.
3. Utilizar argumentos "colgantes", donde para la definición de una función, inmediatamente después del paréntesis de apertura de la misma no se coloque ningún argumento, sino en la línea debajo.
def mi_funcion(
argumento_uno, argumeto_dos,
argumento_tres, argumento_cuatro):
return None
Comentarios y Documentación
Documentar es siempre una buena práctica. Consiste en describir el código en lenguaje natural para obtener una primera aproximación de lo que se estará ejecutando. PEP 8 nos sugiere lo siguiente:
1. Bloques de comentarios (líneas enteras dedicadas a un comentario): Inician con el símbolo # seguido de espacio, y al iniciar una oración hacerlo con la mayúscula correspondiente. No se recomienda específicamente dejar líneas en blanco antes o después, más allá de las recomendaciones anteriores.
def sumar(num1, num2):
# Función que realiza la suma de dos valores (num1 y num2), y
# devuelve su resultado
suma = num1 + num2
return suma
2. Comentarios en línea con el código: se utilizan para recordar o explicar líneas específicas, pero en lugar de hacerlo en un renglón aparte, se realizan en la misma línea del código. No saturar el código con este tipo de comentarios, ya que lo óptimo es que el código pueda explicarse a sí mismo siempre que sea posible, o resultar suficientemente evidente.
Esto no se recomienda:
resultado = numero / 10 # Dividir por diez
Utilización de espacios
PEP 8 nos recomienda utilizar espacios rodeando booleanos, operadores lógicos y aritméticos (+, -, /, *, >, ==, !=, etc.), pero sobre todo para separar los miembros principales de una operación, sin espaciar demasiado el código cuando se llevan a cabo varias de ellas.
if valor>100 and (valor%2==0):
Asimismo, se recomienda no incluir espacios en los siguientes casos:
1. Antes de una coma
2. Antes de un paréntesis, llave o corchete
3. Espacios duplicados (excepto en los casos de los 4 casos de indentación).
Hemos visto varios ejemplos de convenciones de la guía de estilo PEP 8, y aún quedan otros por mencionar, pero los anteriores se encuentran entre los principales. Si los aplicas, en muy poco tiempo estarás creando código de mayor calidad y sin esfuerzo adicional. Recuerda que puedes encontrar la guía detallada en la documentación oficial: https://peps.python.org/pep-0008/
