¿Qué es un docstring?

Un docstring en Python es una cadena de texto que se utiliza para documentar el propósito y el funcionamiento de un módulo, clase, método o función. Los docstrings son una forma importante de hacer que tu código sea más legible y comprensible, tanto para ti como para otros desarrolladores que trabajen con tu código en el futuro.

Los docstrings se colocan justo debajo de la definición de un módulo, clase o función, y se delimitan con triples comillas dobles """ o triples comillas simples '''.

¿Cómo se usan los docstrings?

Los docstrings se usan para describir lo que hace una función, qué parámetros acepta, qué valor devuelve, y cualquier otra información relevante que pueda ser útil para entender cómo usar esa función.

Ejemplo básico de docstring en una función


1def suma(a, b):
2    """
3    Esta función suma dos números y devuelve el resultado.
4
5    Parámetros:
6    a (int, float): El primer número.
7    b (int, float): El segundo número.
8
9    Devuelve:
10    int, float: La suma de a y b.
11    """
12    return a + b
13
14# Llamar a la función y mostrar el resultado
15resultado = suma(3, 5)
16print(f"El resultado de la suma es: {resultado}")
17
18# Mostrar el docstring de la función suma
19print(suma.__doc__)
Salida de Consola!:
El resultado de la suma es: 8

Esta función suma dos números y devuelve el resultado.

Parámetros:
a (int, float): El primer número.
b (int, float): El segundo número.

Devuelve:
int, float: La suma de a y b.

¿Qué hace este código?:
- Define una función suma que toma dos parámetros y devuelve su suma.
- El docstring describe qué hace la función, qué parámetros toma, y qué devuelve.
- Después de llamar a la función, se imprime su resultado.
- Finalmente, se imprime el docstring de la función usando suma.__doc__.

Ejemplo de docstring en una clase


1class Perro:
2    """
3    Una clase simple para representar un perro.
4
5    Atributos:
6    nombre (str): El nombre del perro.
7    edad (int): La edad del perro.
8
9    Métodos:
10    ladrar(): Imprime un mensaje indicando que el perro está ladrando.
11    """
12
13    def __init__(self, nombre, edad):
14        """
15        Inicializa un nuevo perro con un nombre y una edad.
16
17        Parámetros:
18        nombre (str): El nombre del perro.
19        edad (int): La edad del perro.
20        """
21        self.nombre = nombre
22        self.edad = edad
23
24    def ladrar(self):
25        """Imprime un mensaje indicando que el perro está ladrando."""
26        print(f"{self.nombre} está ladrando: ¡Guau, guau!")
27
28# Crear un objeto de la clase Perro
29mi_perro = Perro("Fido", 3)
30
31# Llamar al método ladrar
32mi_perro.ladrar()
33
34# Mostrar el docstring de la clase Perro
35print(Perro.__doc__)
36
37# Mostrar el docstring del método ladrar
38print(Perro.ladrar.__doc__)
Salida de Consola!:
Fido está ladrando: ¡Guau, guau!

Una clase simple para representar un perro.

Atributos:
nombre (str): El nombre del perro.
edad (int): La edad del perro.

Métodos:
ladrar(): Imprime un mensaje indicando que el perro está ladrando.

Imprime un mensaje indicando que el perro está ladrando.

¿Qué hace este código?:
- Define una clase Perro con un docstring que describe la clase, sus atributos y métodos.
- Cada método de la clase también tiene un docstring que describe su funcionalidad.
- Se crea un objeto mi_perro y se llama al método ladrar.
- Finalmente, se imprimen los docstrings de la clase y del método ladrar.

¿Por qué usar docstrings?

Documentación: Los docstrings proporcionan una forma conveniente de documentar tu código, lo que facilita su comprensión y mantenimiento.
Ayuda en el desarrollo: Las herramientas de desarrollo y los entornos de desarrollo integrado (IDE) pueden mostrar los docstrings cuando estás utilizando una función o clase, ayudándote a recordar cómo usarla.
Buenas prácticas: Es una buena práctica documentar tu código, especialmente cuando trabajas en proyectos más grandes o colaborativos.

Conclusión