PEP8

gives coding conventions for the Python code comprising the standard library in the main Python distribution

¿Qué es?

PEP 8, que significa "Python Enhancement Proposal 8", es un documento que proporciona directrices sobre el estilo de código y la escritura de programas en el lenguaje de programación Python. Este PEP fue escrito por Guido van Rossum, el creador de Python, y otros colaboradores, y se centra en mejorar la legibilidad y la consistencia del código Python.

Las principales áreas abordadas por PEP 8 incluyen:

Indentación:
- Utilizar cuatro espacios por nivel de indentación.
Longitud de línea:
- Limitar la longitud de una línea de código a 79 caracteres, o 72 para docstrings y comentarios.
Espacios en blanco:
- Usar espacios en blanco de manera consistente y evitar espacios en blanco al final de las líneas.
Convenciones de nombres:
- Utilizar el estilo snake_case para funciones, variables y métodos.
- Utilizar el estilo CamelCase para clases.
Importaciones:
- Agrupar las importaciones de bibliotecas estándar, bibliotecas de terceros y módulos locales.
- Evitar importaciones absolutas cuando sea posible.
Comentarios:
- Escribir comentarios de manera clara y concisa. Evitar comentarios obvios o innecesarios.
Docstrings:
- Incluir docstrings para explicar el propósito y el funcionamiento de funciones, clases y módulos.
- Seguir el formato de docstring especificado en PEP 257.
Operadores y espacios en blanco:
- Colocar un espacio alrededor de los operadores y después de las comas en listas y tuplas.

PEP 8 se ha convertido en una guía de estilo ampliamente adoptada en la comunidad Python. Adoptar estas convenciones no solo mejora la legibilidad del código, sino que también ayuda a mantener la consistencia en proyectos grandes y colaborativos. Hay herramientas automáticas, como linters, que pueden ayudar a verificar el cumplimiento de PEP 8 en el código Python.

Ejemplo

El siguiente es un ejemplo de código que sigue las directrices de PEP 8 y otro que no. Ambos ejemplos son funciones sencillas en Python:

Código que no sigue PEP 8:

def CalcularSuma ( a, b ) :
    """Esta funcion calcula la suma de dos numeros."""
    Resultado = a+b
    Return Resultado


class clase_ejemplo:
    def __init__ (self, nombre ):
        self.Nombre=nombre

    def mostrar_saludo(self):
        print( f"Hola, {self.Nombre}!" )


# Llamada a la funcion
resultado = CalcularSuma( 3, 5 )
print( resultado )

# Creacion de una instancia de la clase y llamada a un metodo
objetoEjemplo=clase_ejemplo("Usuario")
objetoEjemplo.mostrar_saludo()

Código siguiendo PEP 8:

def calcular_suma(a, b):
    """Esta función calcula la suma de dos números."""
    resultado = a + b
    return resultado


class ClaseEjemplo:
    def __init__(self, nombre):
        self.nombre = nombre

    def mostrar_saludo(self):
        print(f"Hola, {self.nombre}!")


# Llamada a la función
resultado = calcular_suma(3, 5)
print(resultado)

# Creación de una instancia de la clase y llamada a un método
objeto_ejemplo = ClaseEjemplo("Usuario")
objeto_ejemplo.mostrar_saludo()

Observe las diferencias entre los dos ejemplos:

El primero sigue las convenciones de PEP 8, utilizando nombres descriptivos en minúsculas para funciones y métodos (calcular_suma, mostrar_saludo) y en CamelCase para clases (ClaseEjemplo).
El segundo no sigue PEP 8, utilizando nombres de funciones y variables en CamelCase y minúsculas, espacios adicionales alrededor de los paréntesis y en el retorno de la función, y otros estilos que no cumplen con las directrices.

Adherirse a PEP 8 ayuda a que el código sea más legible y consistente, facilitando la colaboración y el mantenimiento del código en proyectos más extensos.

Convenciones destacadas

Indentación en Python según PEP 8:

La indentación en programación se refiere a la estructuración visual del código mediante la alineación de bloques de código. En Python, a diferencia de otros lenguajes que utilizan llaves o palabras clave como begin y end para delimitar bloques de código, se utiliza la indentación para indicar la estructura del programa.

PEP 8, la guía de estilo para código Python, establece directrices específicas sobre la indentación para promover la consistencia y legibilidad del código. La recomendación principal es utilizar espacios en lugar de tabulaciones y establecer un nivel de indentación de cuatro espacios.

"Spaces are the preferred indentation method. Tabs should be used solely to remain consistent with code that is already indented with tabs. Python 3 disallows mixing the use of tabs and spaces for indentation. In Python 2, mixing tabs and spaces is allowed but is discouraged."

Tamaño de la línea

El PEP 8 de Python establece directrices específicas respecto al tamaño de línea en el código fuente. El tamaño de línea recomendado es de 79 caracteres, y existe un límite estricto de 72 caracteres para comentarios y docstrings.

La sección específica sobre el tamaño de línea en el PEP 8 indica lo siguiente:

Límite de 79 caracteres:
- Se recomienda que las líneas de código no excedan los 79 caracteres. Esto incluye tanto el código como los comentarios, excluyendo las líneas de docstrings.
Límite de 72 caracteres para docstrings y comentarios:
- Para comentarios y docstrings, se establece un límite más estricto de 72 caracteres. Esto se hace para asegurar que el código sea fácilmente legible incluso en pantallas más pequeñas o en ventanas divididas.

La razón detrás de estos límites es mejorar la legibilidad del código y facilitar la visualización del código en varios entornos, como editores de texto y pantallas divididas. Un código que se ajusta a estos límites suele ser más fácil de leer y entender, especialmente cuando se trabaja en colaboración o durante revisiones de código.

Ejemplo de código siguiendo las directrices de tamaño de línea en PEP 8:

# Límite de 79 caracteres
def funcion_de_ejemplo(argumento1, argumento2, argumento3):
    resultado = argumento1 + argumento2 + argumento3
    return resultado

# Límite de 72 caracteres para docstring
def funcion_con_docstring():
    """
    Esta es una función de ejemplo con un docstring que no debe
    exceder los 72 caracteres de ancho.
    """
    pass

Comentarios

El PEP 8 de Python ofrece pautas específicas sobre cómo deben ser escritos y utilizados los comentarios en el código. A continuación, se resumen algunas de las recomendaciones clave relacionadas con los comentarios según el PEP 8:

Estilo de Comentarios:
- Utilizar comentarios completos de línea en lugar de comentarios en línea al final del código.
- Evitar comentarios triviales o innecesarios.
Bloques de Comentarios:
- Si es necesario, utilizar bloques de comentarios para explicar secciones más grandes de código.
Comentarios en Docstrings:
- Siempre escribir docstrings para funciones, clases y módulos. Los docstrings son más extensos y proporcionan documentación incorporada.
Comentarios en Línea:
- Limitar la longitud de los comentarios en línea a 72 caracteres.
- Colocar un espacio después del símbolo # en los comentarios en línea.
Comentarios en el Código:
- Evitar comentarios obvios o redundantes.
- Utilizar comentarios para explicar el "por qué" del código, en lugar de simplemente repetir lo que el código está haciendo.
Comentarios TODO:
- Utilizar comentarios TODO para marcar código que necesita ser mejorado o completado posteriormente.

Ejemplo de Comentarios según PEP 8:

# Comentario en línea
resultado = a + b  # Suma de dos números

# Bloque de comentario
"""
Este es un bloque de comentario que explica una sección más grande de código.
Puede contener múltiples líneas y proporciona información adicional sobre
el propósito o la lógica detrás del código.
"""

# Función con docstring
def funcion_ejemplo(argumento1, argumento2):
    """
    Esta función realiza una operación específica.
    
    :param argumento1: Descripción del primer argumento.
    :param argumento2: Descripción del segundo argumento.
    :return: Resultado de la operación.
    """
    pass

# Comentario TODO
# TODO: Agregar manejo de errores aquí

Estas directrices buscan fomentar la creación de comentarios útiles y significativos que mejoren la comprensión del código sin añadir ruido innecesario. Además, los docstrings se consideran una forma preferida de proporcionar documentación más extensa para funciones, clases y módulos.

Como escribir los elementos

El PEP 8 de Python proporciona directrices detalladas sobre el formato de escribir elementos como variables, funciones y clases. A continuación, se resumen algunas de las recomendaciones clave relacionadas con la convención de nombres en PEP 8:

Convenciones de Nombres:
- Utilizar nombres descriptivos para variables, funciones y clases. La claridad en los nombres es preferible a la brevedad.
- Evitar nombres de una sola letra, a menos que sean comúnmente utilizados (como i para un índice en un bucle).
Funciones y Variables:
- Utilizar el estilo snake_case para nombres de funciones y variables (minúsculas con guiones bajos entre palabras).
- Ejemplos:
```
def calcular_suma(a, b):
    pass

nombre_usuario = "Ejemplo"
```
Clases:
- Utilizar el estilo CamelCase para nombres de clases (iniciales en mayúsculas y sin guiones bajos entre palabras).
- Ejemplo:
```
class MiClase:
    pass
```
Constantes:
- Utilizar MAYÚSCULAS con guiones bajos para nombres de constantes.
- Ejemplo:
```
CONSTANTE_PI = 3.14159
```
Módulos:
- Utilizar nombres en minúsculas con guiones bajos para los nombres de los módulos.
- Ejemplo:
```
import modulo_ejemplo
```
Funciones Privadas:
- Utilizar un guion bajo al principio para funciones que se consideran "privadas" dentro de un módulo.
- Ejemplo:
```
def _funcion_privada():
    pass
```
Acrónimos y Nombres de Clases:
- Utilizar mayúsculas solo para la primera letra de un acrónimo o para nombres de clases.
- Ejemplo:
```
from xml.etree import ElementTree as ET
```

Estas convenciones de nombres buscan crear un estilo de código consistente y legible en toda la comunidad de Python. La adhesión a estas reglas facilita la colaboración y mejora la comprensión del código.

" vs '

El PEP 8 de Python proporciona directrices claras sobre el uso de comillas simples (') y dobles (") en el código. Aquí están las recomendaciones principales:

Consistencia:
- Se permite el uso de comillas simples o dobles para definir cadenas en Python.
- La elección entre comillas simples y dobles debe basarse en la consistencia dentro del código o en el estilo adoptado en el proyecto.
Selección de comillas:
- Al elegir comillas, si una cadena ya contiene uno de los tipos de comillas, se puede utilizar el otro para evitar la necesidad de escapar caracteres.
- Ejemplo:
```
cadena_con_comillas_simples = 'Esta cadena contiene una comilla doble: "'
cadena_con_comillas_dobles = "Esta cadena contiene una comilla simple: '"
```
Uso de comillas triples:
- Se pueden usar comillas triples (''' o """) para cadenas multilínea.
- Cuando se usan comillas triples, es preferible usar triple comilla doble para evitar problemas de codificación (PEP 257).
- Ejemplo:
```
cadena_multilinea = """Esta es una cadena
que abarca varias líneas."""
```

Estas recomendaciones se centran en la consistencia y la legibilidad del código. La idea es evitar mezclar estilos de comillas dentro del mismo código para mantener un estilo coherente. La elección entre comillas simples y dobles es en gran medida una cuestión de preferencia o convención del equipo, y ambas son igualmente válidas en términos de sintaxis de Python.

PEP8

¿Qué es?​

Ejemplo​

Convenciones destacadas​

Indentación en Python según PEP 8:​

Tamaño de la línea​

Comentarios​

Como escribir los elementos​

" vs '​