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:
- Acción u objetivo (qué hace).
- Elementos que la conforman (desde variables y parámetros hasta módulos completos).
- 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.
| 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():