Saltar al contenido principal

PEP8 - Escribiendo de manera implícita (Borrador)

La PEP8 es una guía que indica las convenciones estilísticas a seguir para escribir código Python. Se trata de un conjunto de recomendaciones cuyo objetivo es ayudar a escribir código más legible y abarca desde cómo nombrar variables, al número máximo de caracteres que una línea debe tener.

De acuerdo con Guido van Rossum, el código es leído más veces que escrito, por lo que resulta importante escribir código que no sólo funcione correctamente, sino que además pueda ser leído con facilidad. Esto es precisamente lo que veremos en este artículo.

Recomiendo encarecidamente leerse almenos una vez toda la guia oficial de pep8, en este apartado pondre las que considero que son las mas frecuentes asi que si conoces alguna que no este, es por que no la considere tan relevante o frecuente.

Dos mismos códigos pueden realizar lo mismo funcionalmente, pero si no se siguen unas directrices estilísticas, se puede acabar teniendo un código muy difícil de leer.

Por eso tres buenas razones para romper una regla en particular:

  • Cuando el aplicar la regla haga el código menos legible o confuso, incluso para alguien que está acostumbrado a leer códigos que se rigen bajo las indicaciones de este documento.

  • Para ser consistente en código que también la rompe (tal vez por razones históricas) – aunque esto podría ser una oportunidad para limpiar el “desastre” de otra persona.

  • Cuando el equipo de trabajo establece ciertas reglas debido a un objetivo o trabajo comun, por ejemplo si todos usan cierta resolucion o tamaño de pantalla, se podria cambiar el limite de caracteres por linea.

Los problemas más frecuentes en los codigos de Python suelen ser:

  • Líneas demasiado largas.
  • Nombres de variables y clases.
  • Código mal comentado.
  • Uso incorrecto de espacios y líneas en blanco.
  • Código mal identado.
  • Importaciones desordenadas o mal agrupadas
  • Codificaciones (aun que menos frecuente)

Aunque es cierto que ciertas directrices pueden resultar arbitrarias, Python define en la PEP8 las normas estilísticas a seguir para cualquier código parte de la librería estándar, por lo que queda al criterio de cada uno usar estas recomendaciones o no. Sin embargo, prácticamente cualquier código o librería usado por gran cantidad de personas, emplea estas recomendaciones, al haber un amplio consenso en la comunidad.

1-Líneas demasiado largas​

A veces no es intencionalmente, especialmente con las diferentes dimenciones de pantalla u orientaciones de las mismas (para aquellos que usan pantallas verticales para leer codigo) por lo que debieran establecer la cantidad maxima de caracteres por linea, se recomienta limitar todas las líneas a un máximo de 72 caracteres, aun que es permitido limitarlo a 79 para el caso de los "docstrings" o comentarios. Una buena consideración antes de cambiar la longitud es considerar que existen profesionales que trabajan con la pantalla dividida, por lo que ese tamaño es perfecto para trabajar asi de tener una pantalla grande.

En el caso de usar VSCode, puedes hacerlo añadiendo a settings.json

"editor.rulers": [
    {
        "column": 72,
    },
    {
        "column": 79,
        "color": "#491a1a"
    },
],

2-Nombres de variables y clases.​

A-Nombres de variables poco explicativos.​

Esto es algo que es bastante común incluso para algunos profesores de ciertas plataformas online, parte de escribir bien codigo, es que sea explicativo o mas bien, explicito

print(x)

les pregunto, ¿Que diantres es x? en cambio si fuera explicito seria mucho mas facil

print(nombre)

B-Convenciones al Nombrar Elementos​

Esto es para aquellos que llegan de otro lenguaje o simplemente se les olvida. Pero Python define cómo nombrar a cada tipo de la siguiente manera:

  • Funciones: Letras en minúscula separadas por barra baja: funcion, mi_funcion_de_prueba.
  • Variables: Al igual que las funciones: variable, mi_variable.
  • Clases: Uso de CamelCase, usando mayúscula y sin barra baja: MiClase, ClaseDePrueba.
  • Métodos: Al igual que las funciones, usar snake case: metodo, mi_metodo.
  • Constantes: Nombrarlas usando mayúsculas y separadas por barra bajas: UNA_CONSTANTE, OTRA_CONSTANTE.
  • Módulos: Igual que las funciones: modulo.py, mi_modulo.py.
  • Paquetes: En minúsculas pero sin separar por barra bajas: packete, mipaquete

C-Evita usar palabras reservadas o que confundan al lector​

  • Evitar usar palabras reservadas. Si es necesario usar una palabra reservada como class, usar class_ como alternativa.
  • Para métodos mágicos usar siempre init, pero no son nombres que debemos crear sino reutilizar los que Python nos ofrece.

3-Código mal comentado.​

Si un fragmento de codigo:

  • No se puede leer simplemente, seria bueno comentarlo.
  • Es muy importante, deberias recalcarlo.

4-Uso incorrecto de espacios y líneas en blanco.​

Separa funciones de alto nivel y definiciones de clase con dos líneas en blanco.

Definiciones de métodos dentro de una clase son separadas por una línea en blanco.

Líneas en blanco adicionales pueden ser utilizadas (escasamente) para separar grupos de funciones relacionadas. Se pueden omitir entre un grupo (de funciones) de una línea relacionadas (por ejemplo, un conjunto de implementaciones ficticias). Usa líneas en blanco en funciones, escasamente, para indicar secciones lógicas.

5-Código mal identado​

Usa 4 (cuatro) espacios por indentación​

Trata de configurar tu IDE para usar espacios en vez de tabs, sera mas facil trabajar ya que python usa identaciones, y estas son multiplos de 4 espacios (E112, E113, E114). Sin embargo, lo mas importante, Nunca mezcles tabulaciones y espacios.

Las líneas de continuación deben alinearse verticalmente​

Las líneas de continuación deben alinearse verticalmente con el carácter que se ha utilizado (paréntesis, llaves, corchetes)(E113, E113, E117, E122) o haciendo uso de la “hanging indent”(E121) (aplicar tabulaciones en todas las líneas con excepción de la primera). Al utilizar este último método, no debe haber argumentos en la primera línea, y más tabulación debe utilizarse para que la actual se entienda como una (línea) de continuación.

El paréntesis / corchete / llave que cierre una asignación debe estar alineado con el primer carácter que no sea un espacio en blanco (E123, E124):

-E115 Expected an indented block (comment) -E116 Unexpected indentation (comment)

-E125 Continuation line with same indent as next logical line -E126 Continuation line over-indented for hanging indent -E127 Continuation line over-indented for visual indent -E128 Continuation line under-indented for visual indent -E129 Visually indented line with same indent as next logical line -E131 Continuation line unaligned for hanging indent -E133 Closing bracket is missing indentation

-E112 Se esperaba un bloque de identación -E113 bloque de identación inesperada -E114 El espacio de identación no es múltiplo de cuatro (comentario) -E115 Se esperaba un bloque de identación (comentario) -E116 Bloque de identación inesperada (comentario) -E117 Sobre bloque de identación -E121 Línea de continuación con bloque de identación insuficiente para bloque de identación -E122 Línea de continuación sin bloque de identación o sin identación -E123 El soporte de cierre no coincide con la identación de la línea del soporte de apertura -E124 El soporte de cierre no coincide con la identación visual -E125 Línea de continuación con la misma identación que la siguiente línea lógica -E126 Línea de continuación con identación excesiva para identación francesa -E127 Línea de continuación con identación excesiva para identación visual -E128 Línea de continuación con identación inferior para identación visual -E129 Línea con identación visual con la misma identación que la siguiente línea lógica -E131 Línea de continuación desalineada para identación francesa -E133 Falta muesca en el soporte de cierre

6-Importaciones desordenadas o mal agrupadas​

Las importaciones siempre se colocan al comienzo del archivo, simplemente luego de cualquier comentario o documentación del módulo, y antes de globales y constantes.

Las importaciones deben estar en líneas separadas a no ser que sean de una misma fuente.

# Sí
import os
import sys

# No
import sys, os

# Sí
from subprocess import Popen, PIPE

Las importaciones deben estar agrupadas en el siguiente orden:

  1. importaciones de la librería estándar
  2. importaciones terceras relacionadas
  3. importaciones locales de la aplicación / librería

Deberías poner una línea en blanco entre cada grupo.

7-Codificaciones (aun que menos frecuente)​

El código en el núcleo de la distribución de Python siempre debería utilizar la codificación ASCII o Latin-1 (alias ISO-8859-1). Para Python 3.0 y en adelante, UTF-8 es preferible ante Latin-1, véase PEP 3120.

Fuentes: