Contenido del curso
Cómo documentar funciones en Python con docstrings
Aprender a escribir docstrings en Python te ayuda a documentar tu código para que tú y otras personas entiendan qué hace cada función sin descifrar línea por línea. Esta guía es para quienes ya programan y quieren dejar código legible en proyectos grandes.
El punto de partida es sencillo: el código se escribe una vez, pero se lee muchas veces. Y aquí viene lo interesante, porque a veces uno mismo vuelve a leer su código y no lo entiende. Para eso sirve la documentación.
Qué es un docstring y por qué documentar tu código
Un docstring es el texto que describe qué hace una función, clase o archivo dentro de tu código. Python define cómo escribirlo mediante una propuesta oficial llamada PEP 257 [00:36], que explica casi todo lo que necesitas para generar documentación clara.
¿Qué es PEP 257? Es la propuesta oficial de Python que define cómo crear docstrings: describir argumentos, valores de retorno y la estructura que debe tener la documentación de cada función o clase.
La razón de documentar es práctica. Cuando trabajas en proyectos grandes, la documentación te permite entender una función solo con leer su descripción corta, sin revisar toda su lógica interna.
Cómo se escribe un docstring con triple comilla
Lo primero que enseña la documentación es que siempre se usan comillas triples [01:12]. La razón es que permiten escribir en varias líneas.
Con esta base, ya puedes empezar a documentar funciones dentro de un archivo como docstrings.py.
python """Explicación de docstrings.
En este archivo explicamos cómo funcionan los docstrings en Python. """
def saludar(): """Esta función retorna un saludo.
Returns: str: un saludo en español. """ return "Hola"
Cómo acceder a la documentación desde el código
Existen varias formas de leer un docstring sin abrir el archivo. Esto es muy útil cuando quieres consultar la documentación de una librería que no tienes a la mano.
Python crea automáticamente un parámetro llamado __doc__ [02:38], que empieza y termina con dos guiones bajos para evitar que alguien lo modifique. Si lo imprimes, devuelve el string de la documentación.
python print(saludar.doc)
Otra manera es usar la función help [03:20]. Al pasarle la función, muestra toda la guía de ayuda; para salir de ese modo presionas la tecla Q.
¿Qué pasa si una función no tiene docstring? Al imprimir su documentación con
__doc__apareceNone, porque no existe texto que describir. Sin docstring, no hay nada que leer.
Además, tu editor de texto muestra esta documentación al pasar el cursor sobre la función: verás la firma, lo que retorna y los tipos que definiste.
Cuál es la estructura de una buena documentación
El PEP 257 enseña que un docstring completo va más allá de una descripción corta. La estructura recomendada incluye varios bloques en orden.
Los ejemplos no son obligatorios, pero aparecen mucho en código profesional y a veces se pueden ejecutar como pruebas unitarias. También conviene especificar los tipos, aunque Python los defina de forma dinámica, siempre es mejor declararlos.
Cómo documentar una función con ayuda de IA
Para documentar la función clean_test [06:00], puedes apoyarte en un modelo de lenguaje. La clave está en pasarle el contexto correcto: como las reglas ya están en PEP 257, se lo indicas al LLM para que genere las variables y el contenido de forma correcta.
El prompt usado fue generar un docstring completo en español siguiendo PEP 257, incluyendo descripción, parámetros, valor de retorno, excepciones y ejemplos. La recomendación general es escribir en inglés, aunque aquí se hizo en español por practicidad.
python def clean_test(text: str) -> str: """Limpia y normaliza el texto eliminando espacios y convirtiendo a minusculas.
Args: text (str): la cadena de texto que sera limpiada y normalizada. Returns: str: el texto limpio y normalizado. Raises: TypeError: si el texto pasado no es de tipo str. Examples: >>> clean_test(" Hola Mundo ") 'hola mundo' """
En el ejemplo, el texto "Hola Mundo" con espacios termina como hola mundo en minúsculas. Con solo leer la descripción corta ya entiendes qué hace la función.
Tres consejos para escribir mejor documentación
La documentación no es obligatoria, pero se vuelve muy fácil de usar cuando trabajas en proyectos grandes. Estos son tres tips prácticos.
El reto de esta clase es recorrer todas las funciones que has creado durante el curso y documentarlas. Cuéntanos en los comentarios qué técnicas usas y qué prompts te dan mejores resultados.
Gabriel Obregón
Estudiante
Samuel Steven Bernal Martínez
Estudiante
Cesar Augusto Mora Castilo
Estudiante
Juan David Santamaria Gomez
Estudiante
Argenis Daniel Nieves Berroeta
Estudiante
Samuel Alejandro Hurtado
Estudiante🐍✨Docstrings en Python
🧠 Idea Clave
La documentación no es opcional, es tu memoria a futuro.
Un docstring explica qué hace tu código, cómo y por qué.
📌 Beneficio: Leer tu propio código después será tan fácil como leer un resumen.
✍️ Qué es un Docstring
📖 Definición rápida: Un docstring es una cadena entre tres comillas """ ... """ que describe el propósito de un módulo, clase o función.
🧩 Dónde se usa:
💡 Ejemplo básico
def saludo_doc():
"""Devuelve un saludo en español.
Retorno:
str: un saludo.
"""
return "Hola"
👉 Tips rápidos
📘 Guía PEP 257
📚 Propósito: establecer una forma estándar de escribir docstrings.
🧱 Estructura ideal
Normalmente en un entorno real se documentan al completo todas las funciones o su mayoría? o normalmente se documenta solo las que son "difíciles" o que puedan confundir?, o quiza se documenta parcialmente y solo a las que son dificiles se le agrega todo lo de PEP 257, me gustaría saber eso de cara a proyectos reales.
Por experiencia propia le puedo sugerir que lo mejor es documentar todo, porque pasa que luego de unas semanas o meses uno olvida detalles de la implementación del código, además se documenta pensando en el futuro (mejoras, escalado), y en otros programadores que pudieran tener que trabajar con ese código y tengan más fácil el trabajo de comprenderlo.
Lo mejor es dejar siempre documentado todo el codigo, por experiencia la vida es mucho mas facil, y te ganas horas leyendo y entendiendo el codigo de un tercero
def fetch_news(api_name: str, *args, **kwargs): """Ejecuta el cliente de noticias especificado inyectando configuración por defecto. Args: api_name: Identificador del servicio ('newapi', 'guardian'). *args: Argumentos posicionales requeridos por el cliente específico. **kwargs: Configuración opcional para sobrescribir la base. Returns: El resultado retornado por la función del cliente seleccionado. Raises: ValueError: Si `api_name` no coincide con ningún cliente registrado. """ base_config = { "timeout": 30, "retries": 3, } config = { **base_config, **kwargs, } api_clients = { "newapi": newsapi_client, "guardian": guardian_client, } try: client = api_clients[api_name] except KeyError: # Falla de forma controlada indicando qué nombre fue incorrecto raise ValueError(f"Cliente '{api_name}' no soportado. Disponibles: {list(api_clients.keys())}") return client(*args, **config)
def clean_text(text: str) -> str:
"""
Clean text by removing punctuation and converting to lowercase.
This function removes punctuation and converts text to lowercase.
Args:
text (str): Text to clean.
Returns:
str: Cleaned text.
Raises:
TypeError: If text is not a string.
Examples:
>>> clean_text("Hello World!")
'hello world'
>>> clean_text("Hello World! 123")
'hello world 123'
"""
if not isinstance(text, str):
raise TypeError("text must be a string")
return text.lower().strip()
