Los docstrings en Python son cadenas de documentación colocadas al inicio de módulos, clases, funciones y métodos. A diferencia de un comentario común, Python conserva el docstring en el atributo __doc__, lo que permite mostrarlo con help() y generar documentación automáticamente.
En esta guía aprenderás docstrings de una línea y multilínea, parámetros, retornos, excepciones, ejemplos, clases, módulos, convenciones y herramientas. La referencia principal es la PEP 257 sobre convenciones de docstrings.
Tu primer docstring
def saludar(nombre):
"""Devuelve un saludo para la persona indicada."""
return f"Hola, {nombre}."El docstring aparece inmediatamente después de la definición y utiliza comillas triples. Puedes inspeccionarlo:
print(saludar.__doc__)
help(saludar)Docstring de una línea
Para una función sencilla, resume la acción con una frase imperativa o descriptiva.
def es_par(numero):
"""Indica si el número recibido es par."""
return numero % 2 == 0No repitas solamente el nombre ni describas la sintaxis obvia.
Docstring multilínea
def dividir(dividendo, divisor):
"""Divide dos números.
Args:
dividendo: Valor que será dividido.
divisor: Valor utilizado como divisor.
Returns:
El resultado de la división.
Raises:
ValueError: Si el divisor es cero.
"""
if divisor == 0:
raise ValueError("El divisor no puede ser cero")
return dividendo / divisorLa primera línea resume. Después de una línea en blanco, el cuerpo explica el contrato público.
Qué documentar
- Qué hace la función o clase.
- Significado y restricciones de los parámetros.
- Valor devuelto y casos especiales.
- Excepciones que forman parte del contrato.
- Efectos secundarios importantes.
- Ejemplos cuando aclaren un uso no obvio.
La guía de funciones en Python ayuda a diseñar interfaces pequeñas que pueden documentarse con claridad.
Formatos comunes
Python no obliga a usar un formato único. Los estilos más habituales son Google, NumPy y reStructuredText. Elige uno según las herramientas y mantenlo en todo el proyecto.
Estilo Google
def buscar_usuario(usuario_id, incluir_inactivo=False):
"""Busca un usuario por identificador.
Args:
usuario_id: Identificador numérico del usuario.
incluir_inactivo: Incluye cuentas inactivas si es True.
Returns:
Un diccionario con los datos o None si no existe.
"""
...Estilo NumPy
def buscar_usuario(usuario_id, incluir_inactivo=False):
"""Busca un usuario por identificador.
Parameters
----------
usuario_id : int
Identificador numérico del usuario.
incluir_inactivo : bool, optional
Incluye cuentas inactivas.
Returns
-------
dict | None
Datos del usuario o None.
"""
...Docstrings y type hints
def calcular_total(
precios: list[float],
descuento: float = 0.0,
) -> float:
"""Calcula el total después de aplicar un descuento.
Args:
precios: Precios no negativos.
descuento: Fracción entre 0 y 1.
Returns:
Total final de la compra.
Raises:
ValueError: Si el descuento queda fuera del intervalo.
"""
if not 0 <= descuento <= 1:
raise ValueError("Descuento no válido")
return sum(precios) * (1 - descuento)Los type hints muestran tipos; el docstring explica significado, unidades, restricciones y comportamiento. No dupliques información sin aportar contexto.
Documentar clases
class CuentaBancaria:
"""Representa una cuenta con saldo no negativo.
Attributes:
titular: Nombre de la persona titular.
saldo: Cantidad disponible.
"""
def __init__(self, titular, saldo=0.0):
self.titular = titular
self.saldo = saldo
def depositar(self, cantidad):
"""Añade una cantidad positiva al saldo."""
if cantidad <= 0:
raise ValueError("La cantidad debe ser positiva")
self.saldo += cantidadEl docstring de clase describe el propósito y el estado público. Cada método documenta su propio contrato. La guía de programación orientada a objetos en Python explica clases y métodos.
Docstring de módulo
"""Herramientas para generar informes de ventas.
El módulo carga registros, valida columnas y crea resúmenes
por categoría. No modifica el archivo de origen.
"""
from pathlib import PathEl docstring aparece antes de los imports, salvo elementos especiales como el shebang o la declaración de codificación.
Documentar excepciones
Documenta excepciones que el usuario de la función puede prever y manejar.
def cargar_configuracion(ruta):
"""Carga una configuración JSON.
Raises:
FileNotFoundError: Si la ruta no existe.
ValueError: Si el JSON no contiene la estructura requerida.
"""
...No hace falta enumerar cada error interno posible. La guía de try y except en Python ayuda a definir excepciones útiles.
Añadir ejemplos ejecutables
def duplicar(numero):
"""Devuelve el doble de un número.
Examples:
>>> duplicar(4)
8
>>> duplicar(-2)
-4
"""
return numero * 2Los ejemplos con formato interactivo pueden ejecutarse con doctest cuando son deterministas y pequeños.
python -m doctest -v modulo.pyGenerar documentación con pydoc
La herramienta estándar pydoc obtiene información de los docstrings.
python -m pydoc mi_modulo
python -m pydoc -w mi_moduloPara proyectos grandes, herramientas como Sphinx o MkDocs pueden convertir docstrings y archivos Markdown en un sitio completo.
Comentarios y docstrings no son lo mismo
- Un comentario explica una decisión interna para quien lee el código.
- Un docstring describe cómo utilizar una interfaz pública.
La guía de comentarios en Python muestra cuándo usar cada recurso.
PEP 8 y documentación
PEP 8 se concentra en estilo de código, mientras PEP 257 trata docstrings. Ambas buscan legibilidad y consistencia. Consulta la guía de PEP 8 en Python para nombres, imports y formato.
Probar documentación y comportamiento
Los ejemplos de docstring no reemplazan una suite de pruebas. Utiliza tests para casos límite, excepciones y reglas de negocio. La guía de pruebas unitarias en Python muestra cómo organizar estas verificaciones.
Errores frecuentes
- Repetir el nombre de la función sin explicar su contrato.
- Dejar documentación desactualizada después de cambiar el código.
- Documentar detalles internos inestables como si fueran públicos.
- Combinar varios estilos en el mismo proyecto.
- Duplicar type hints sin añadir significado.
- Prometer excepciones o retornos que la implementación no cumple.
- Escribir docstrings enormes para funciones que deberían dividirse.
Lista de revisión
- ¿La primera línea resume claramente?
- ¿Los parámetros tienen significado y restricciones?
- ¿El retorno está descrito?
- ¿Las excepciones públicas están documentadas?
- ¿Los ejemplos siguen funcionando?
- ¿El formato es consistente con el proyecto?
Conclusión
Los docstrings en Python transforman una función en una interfaz comprensible para personas y herramientas. Escribe un resumen breve, documenta contratos y restricciones, mantén los ejemplos actualizados y elige un formato consistente. Cuando una función resulta difícil de documentar, normalmente también conviene revisar su diseño y dividir responsabilidades.
