Cadenas de documentación (docstrings)

Rev. 21/05/2024

Las cadenas de documentación son una excelente manera de proporcionar información contextual sobre los objetos, funciones, clases, métodos y módulos en tu código.

Las docstrings de Python son una característica incorporada del lenguaje que permite realizar comentarios que describan el propósito y uso de los mencionados objetos, funciones, clases, métodos y módulos.

Estos comentarios deben aparecer como primer elemento, antes del código ejecutable, utilizando tres comillas simples (') o tres comillas dobles(").

Aquí hay un ejemplo de cómo se vería un docstrings en una función:

Python

def suma(a, b):
    """
    suma(a, b) -> int

        Esta función toma dos números como argumentos y devuelve la suma de ambos.

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

        Retorna:
            La suma de a y b (int)
    """
    return int(a) + int(b)

Para acceder a la docstrings de una función, método o clase, puede utilizar la función help():

Python

help(suma)

Terminal (Entrada/Salida)

Help on function suma in module __main__:

suma(a, b)
    suma(a, b) -> int

        Esta función toma dos números como argumentos y devuelve la suma de ambos.

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

        Retorna:
            La suma de a y b (int)

o el atributo __doc__:

Python

print(suma.__doc__)

Terminal (Entrada/Salida)

    suma(a, b) -> int

        Esta función toma dos números como argumentos y devuelve la suma de ambos.

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

        Retorna:
            La suma de a y b (int)

>

Tanto el uso help() de como de __doc__ imprimirán la docstrings completa, incluyendo los títulos y las descripciones de los parámetros y la salida.

!Buena práctica!

1. Las docstrings deben ser descriptivas, claras y concisas.

2. Inicia las cadenas de documentación con un resumen conciso.

3. La primera línea de la cadena de documentación debe ser una breve descripción. Si es necesario, se pueden agregar líneas adicionales después de una nueva línea.

4. Para los módulos, la cadena de documentación debe indicar qué hace el módulo.

5. Para las clases, la cadena de documentación debe incluir una breve descripción de la clase, junto con sus atributos y métodos.

6. Para los métodos, la cadena de documentación debe proporcionar una descripción de la funcionalidad del método, junto con una descripción de los parámetros que acepta y el valor que devuelve.

7. Para las funciones, la cadena de documentación debe describir el propósito de la función, sus parámetros y su valor de retorno.

¡Para recordar!

Si no se aplica en la primera línea del objeto, función, clase, método o módulo, el intérprete no lo tomará como una docstrings.

Para acceder a las cadenas de documentación puedes utilizar el atributo __doc__.

Si utilizas Visual Studio Code para programar, el atajo (shortcut) para convertir varias líneas de código en una cadenas de documentación es SHIFT + ALT + A.

Conclusiones

Las docstrings son una excelente herramienta para documentar y mantener tu código, ya que proporcionan información adicional sobre cómo funciona y se espera que funcione este.

Además, muchas herramientas de desarrollo e integración continua, como Sphinx, Pylint y pydoc, utilizan docstrings para generar documentación y realizar análisis estáticos del código.

Para mayor información, visitar https://pandas.pydata.org/docs/index.html haciendo clic aquí.