Documentación en Python con docstrings y PEP 257

La documentación en Python no es un lujo: es una herramienta para leer y entender tu propio código en el futuro. Con docstrings bien escritos, podrás saber qué hace cada función o clase sin adivinar. Aquí verás cómo usar las tres comillas, qué indica el PEP 257, cómo consultar la ayuda con doc y help, y cómo apoyarte en IA para documentar rápido y bien.

¿Qué es un docstring en Python y por qué documentar código?

Documentar evita confusiones al releer código. La mayoría de las veces no vuelves a cambiar el código: lo vuelves a leer. Un docstring es un texto entre tres comillas que describe módulos, funciones o clases.

• Tres comillas permiten múltiples líneas en una sola cadena de texto.
• Cada archivo puede empezar con un docstring de módulo claro.
• Funciones y clases deben tener docstrings que expliquen propósito y uso.

¿Cómo iniciar con triple comillas?

"""
Explicación de docstrings en Python.
Permite escribir documentación multilínea para archivos, funciones y clases.
"""

# Ejemplo sin docstring
def saludo():
    return "Hola"

# Ejemplo con docstring
def saludo_doc():
    """Esta función devuelve un saludo.

    Retorno:
        str: un saludo en español.
    """
    return "Hola"

• Usa múltiples líneas para dar claridad.
• Evita textos crípticos: sé directo y específico.

¿Cómo se escriben y consultan docstrings según PEP 257?

El PEP 257 propone la anatomía de una buena documentación. Empieza con una descripción corta, luego opcionalmente una explicación larga, parámetros, retorno, excepciones y ejemplos. Además, puedes consultar esa ayuda desde consola o el editor.

¿Cómo estructurar el docstring según PEP 257?

def limpiar_texto(texto: str) -> str:
    """Limpia y normaliza el texto removiendo espacios y convirtiendo a minúsculas.

    Descripción:
        esta función toma la cadena de texto y realiza operaciones de limpieza.

    Parámetros:
        texto (str): cadena de texto que se va a limpiar y normalizar.

    Retorno:
        str: texto limpio y normalizado.

    Excepciones:
        TypeError: si texto no es de tipo str.

    Ejemplos:
        >>> limpiar_texto("  Hola, mundo  ")
        'hola, mundo'
    """
    if not isinstance(texto, str):
        raise TypeError("texto debe ser str")
    return texto.strip().lower()

• Tipos explícitos ayudan al editor y a quien lee (ver typing y anotaciones como texto: str y -> str).
• Ejemplos tipo doctest (>>>) muestran entradas y salidas esperadas.

¿Cómo consultar la documentación en consola y editor?

print(saludo_doc.__doc__)   # Accede al atributo protegido __doc__
help(saludo_doc)            # Abre la guía interactiva; presiona Q para salir

• Con __doc__ obtienes el texto del docstring directamente.
• Con help() ves firma, retorno y la ayuda completa.
• En el editor, al pasar el cursor, se muestra la firma, el retorno y la documentación con tipos.

¿Cómo usar IA y buenas prácticas para documentar?

Puedes aprovechar Cloud Code u otro entorno para pedir a un LLM que redacte docstrings completos. Proporciona el código y el contexto del PEP 257 para que genere descripción, parámetros, retorno, excepciones y ejemplos en español cuando lo necesites.

¿Qué prompt usar para generar un docstring?

Genera un docstring completo en español. Sigue el PEP 257 para esta función.
Incluye: descripción, parámetros, retorno, excepciones y ejemplos.

• Recomendación general: se sugiere inglés, pero usar español facilita para hispanohablantes.
• Verifica la salida: debe reflejar lo que realmente hace la función.

¿Qué buenas prácticas elevan la calidad?

• Sé conciso y claro: pide menos relleno y más precisión.
• Mantén la documentación actualizada: ajusta cuando cambie la funcionalidad.
• Documenta ejemplos: facilitan entender el comportamiento real.

¿Ya documentaste tus funciones del curso? Comparte en comentarios tus técnicas y los prompts que mejor te funcionan para generar docstrings útiles y consistentes.