🧪 Python Nivel 2 – Parte 13: Documentar tu Código con Docstrings y Buenas Prácticas

 

🎯 ¿Qué aprenderás?

✅ Qué es un docstring y cómo escribirlo correctamente
✅ Cómo documentar funciones, clases y módulos
✅ Cómo generar documentación automática
✅ Buenas prácticas para que tu código sea más legible y mantenible

---

🧱 ¿Qué es un Docstring?

Un docstring es un texto descriptivo que se coloca justo después de la definición de una función, clase o módulo.
Se escribe entre triples comillas (""" """") y sirve para explicar qué hace, qué parámetros recibe y qué devuelve.

---

🧑‍💻 Ejemplo de función con docstring

def saludar(nombre):
    """
    Devuelve un saludo personalizado.

    Parámetros:
    nombre (str): El nombre de la persona a saludar.

    Retorna:
    str: Un saludo con el nombre.
    """
    return f"Hola, {nombre}!"

---

📦 Docstring en una clase

class Usuario:
    """
    Representa un usuario con nombre y email.
    """

    def __init__(self, nombre, email):
        """
        Inicializa un nuevo usuario.

        Parámetros:
        nombre (str): Nombre del usuario.
        email (str): Correo electrónico del usuario.
        """
        self.nombre = nombre
        self.email = email

---

🧰 Buenas prácticas al documentar

✔️ Usa lenguaje claro y conciso
✔️ Explica entradas y salidas
✔️ Usa estilo PEP 257 (recomendado en Python)
✔️ Incluye ejemplos cuando sea útil

---

🧪 Acceder al docstring en tiempo de ejecución

print(saludar.__doc__)
help(saludar)

---

📄 Docstring de módulo

Coloca un docstring al principio del archivo .py:

"""
Módulo para gestionar usuarios y sus datos.

Contiene:
- Clase Usuario
- Funciones de validación
"""

---

🚀 ¿Qué aprendiste hoy?

✔️ A escribir documentación integrada con docstrings
✔️ A aplicar buenas prácticas de código limpio
✔️ A facilitar el mantenimiento de tus programas
✔️ A comunicarte mejor con tu futuro yo (o tu equipo)

---

📂 Ejemplos documentados en GitHub:
github.com/josecodetech

🎥 Video paso a paso en YouTube:
https://www.youtube.com/watch?v=DKz0CfiSbFs