Libro Python Aplicado de Eugenia Bahit. GNU/Linux, ciencia de datos, y desarrollo web

Banner de Python Aplicado

Docstrings (cadenas de documentación)


Cita con formato IEEE:
E. Bahit, "Docstrings (cadenas de documentación)", in Python Aplicado, 4th ed., EBRC Publisher, 2022, pp. 61–64.

Cita con formato APA 7:
Bahit, E. (2022). Docstrings (cadenas de documentación). In Python Aplicado (4th ed., pp. 61–64). EBRC Publisher.

Cita en línea:
(Bahit, 2022)

La documentación del código fuente no se refiere al hecho de escribir líneas de comentarios en los archivos, sino a una práctica metódica mediante la cual se describen tres aspectos técnicos de las estructuras de control:
  1. Acción u objetivo (qué hace).
  2. Elementos que la conforman (desde variables y parámetros hasta módulos completos).
  3. Resultados que pueden esperarse (qué retorna o produce).

Estos tres aspectos, por lo general, deberían ser suficientes para quien desee hacer uso de los mismos. No obstante, es posible complementarlos con ejemplos de uso.

Los elementos que conforman una documentación convencional, se describen en la siguiente tabla.

Componentes básicos a incluir en la documentación
Elemento Características Ejemplo
Acción Puede referirse tanto al procedimiento llevado a cabo por un método o función, como a la finalidad de una clase, módulo, o biblioteca. En referencia a una función: Calcular un número primo.
En referencia a una clase: Base abstracta para objetos genéricos.
En referencia a una biblioteca: Biblioteca para la generación y cómputo de números primos.
Componentes Se refiere a los datos que maneja la estructura. En el caso de funciones, se refiere a los parámetros que recibe. En el caso de las clases, puede hacer referencia a constantes de clase, e incluso a propiedades (dependiendo del contexto).
En el caso de bibliotecas, puede referirse a variables y constantes disponibles.
Si se trata de un módulo tipo script, también puede referirse a los argumentos que recibe.
Para este tipo de componentes suelen documentarse tres características: nombre de la variable, descripción (que bien puede referirse solo al rol que ocupa o bien al rol y/o al tipo de datos), y valor por defecto si lo hubiere:
alicuota -- índice para el cálculo del IVA (valor por defecto: 10.5)
Retorno Se refiere al valor de retorno tras invocar a una función o método de clase. Retorna el valor dado en el parámetro bruto multiplicado por la alícuota sobre 100.

El código se documenta mediante el uso de cadenas de comentarios, que en inglés se denominan docstrings. En el caso de Python, su modo de escritura se encuentra definido en las Python Enhancement Proposal (PEP) 257.

En las PEP 257 se define una cadena de documentación (docstring) como una cadena de texto que se encuentra como primera sentencia dentro de un módulo, función, clase o método, y que puede ser recuperada mediante el atributo especial __doc__ de dicho elemento.

>>> def foo():
... """Hacer bar y retornar baz"""
...   pass
...
>>> foo.__doc__
'Hacer bar y retornar baz'

A la documentación de un componente también se puede acceder mediante la función help():