Cómo documentar código en Python

Si acabas de empezar con Python y quieres seguir aprendiendo, haz el curso Intermediate Python de DataCamp.

Relevancia de documentar tu proyecto

La documentación es una parte esencial de cualquier proyecto en el que trabajes, independientemente del lenguaje de programación que uses. Un proyecto con varias API en producción y muchos usuarios, pero sin documentación, se consideraría incompleto. Piensa un momento: como desarrollador, ¿cómo te sentirías si quisieras replicar un proyecto o usar parte de él y no tuviera documentación? Integrarlo en tu arquitectura sería, como poco, complicado.

Una buena documentación hará que tu proyecto tenga más éxito, porque cuando lo compartas con el mundo querrás que la gente lo use; y si es de código abierto, este objetivo es aún mayor. También querrás que la comunidad contribuya y lo haga crecer.

El reconocido creador de Python dice que el código se lee más de lo que se escribe. Esta cita subraya la importancia que tiene la documentación para que otros puedan entender e implementar tu código o tu proyecto.

Imagina que trabajas en la empresa XYZ, estás en tu periodo de preaviso y tu mánager quiere que transfieras el proyecto a un compañero. Puedes hacerle una KT (transferencia de conocimiento), pero ¿y si tu compañero no consigue ejecutar correctamente parte del código? Puede haber varias razones: por ejemplo, que los binarios sobre los que corre tu código no coincidan con los de su sistema operativo.

¿Qué es exactamente la documentación?

La documentación tiene varios componentes asociados. Debe estar bien estructurada en torno a ellos y ceñirse a esos componentes para considerarse una documentación adecuada.

A un nivel abstracto, los componentes son:

• Asegurarte de que la base de código de tu proyecto está bien comentada.

• Seguir los estándares de codificación PEP 8 de Python.

• Tutoriales concretos sobre cómo se construyó el proyecto, especialmente si es de código abierto con fines formativos.

• Una guía de instalación de los paquetes y módulos necesarios para crear el software y, si el proyecto incluye hardware, una hoja de especificaciones técnicas. Por ejemplo, cómo instalar Anaconda, TensorFlow, Keras, etc.

• Varias discusiones sobre el avance del proyecto en cada etapa que hayan llevado a la implementación satisfactoria del software.

• Material de referencia que describa técnicamente el stack tecnológico usado durante el desarrollo.

• El diseño arquitectónico del proyecto o de la solución de software.

Estos puntos son solo algunos de los componentes que pueden formar parte de una documentación bien estructurada y completa. Es importante mantenerlos diferenciados, lo que además facilitará el mantenimiento futuro de la documentación.

Un ejemplo de documentación exhaustiva que incluye la mayoría de los componentes comentados sería similar al de abajo:

Mucha gente confunde comentar con documentar y los considera lo mismo. Los comentarios describen tu código para el usuario, el mantenedor e incluso para ti como referencia futura. Funcionan a nivel de código y pueden considerarse un subconjunto de la documentación. Los comentarios ayudan a:

• entender tu código,
• hacerlo autoexplicativo, y
• comprender su propósito y diseño.

Recuerda que, como Python sigue los estándares de codificación PEP 8, los comentarios también deben cumplirlos. La documentación oficial de Python indica que, para bloques largos de texto con pocas restricciones estructurales (docstrings o comentarios), la longitud de línea debe limitarse a 72 caracteres.

Para comprobar si tu código cumple PEP 8, puedes usar el módulo pylint de Python. Este módulo permite modificar el límite de caracteres para comentarios y para el resto de líneas de código.

Veamos un par de ejemplos.

• Descripción de importación de módulo

import tensorflow as tf
#imports tensorflow as tf. Tensorflow is an n-dimensional matrix.
#just like a 1-D vector, 2-D array, 3-D array etc.

• Descripción de definición de variable

n_classes = 10 # MNIST total classes (0-9 digits)

Si quieres profundizar en los comentarios y en sus buenas y malas prácticas, echa un vistazo a este artículo.

Ahora veamos cómo las docstrings pueden ayudarte a documentar la base de código de tu proyecto.

Docstrings para documentar código en Python

Una docstring de Python es una cadena de documentación (string literal) que aparece como la primera instrucción en la definición de una clase, módulo, función o método. Las docstrings son accesibles desde el atributo (__doc__) de cualquier objeto de Python y también a través de la función integrada help(), que resulta muy útil.

Además, las docstrings son ideales para entender la funcionalidad de una parte amplia del código, es decir, el propósito general de una clase, módulo o función. En cambio, los comentarios se usan para líneas y expresiones de código, que suelen ser pequeñas. Son un texto descriptivo que el programador escribe principalmente para sí mismo y para cualquier desarrollador que quiera contribuir al proyecto, indicando qué hace cada línea o expresión. Documentar tu código es esencial para escribir código limpio y programas bien estructurados. Aunque ya se ha mencionado, no existe un único estándar obligatorio para hacerlo.

Hay dos formas de escribir docstrings: de una sola línea y multilínea. Son las que suelen usar científicos de datos y programadores en sus proyectos.

• Las docstrings de una sola línea caben en una línea. Puedes usar comillas triples simples o dobles; las de apertura y cierre deben coincidir. En las docstrings de una sola línea, las comillas de cierre van en la misma línea que las de apertura. La convención habitual es usar comillas triples dobles.

def square(a):
    '''Returned argument a is squared.'''
    return a**a

print (square.__doc__)


help(square)

Returned argument a is squared.
Help on function square in module __main__:

square(a)
    Returned argument a is squared.

• Las docstrings multilínea contienen la misma cadena inicial que las de una línea, pero a continuación dejan una línea en blanco y siguen con el texto descriptivo.

def some_function(argument1):
    """Summary or Description of the Function

    Parameters:
    argument1 (int): Description of arg1

    Returns:
    int:Returning value

   """

    return argument1

print(some_function.__doc__)

Summary or Description of the Function

    Parameters:
    argument1 (int): Description of arg1

    Returns:
    int:Returning value

De la tabla anterior, tomemos Pydoc como uno de los formatos de docstring y explorémoslo un poco.

Como has visto, las docstrings se pueden consultar con el atributo integrado __doc__ y con la función help(). También puedes usar el módulo integrado Pydoc, que ofrece funciones y características muy diferentes en comparación con el atributo doc y la función help.

Pydoc es una herramienta muy útil cuando quieres compartir tu código con tus compañeros o abrirlo a la comunidad, apuntando así a una audiencia mucho más amplia. Puede generar páginas web a partir de tu documentación en Python e incluso lanzar un servidor web.

Veamos cómo funciona.

La forma más sencilla y práctica de ejecutar el módulo Pydoc es lanzarlo como script. Para ejecutarlo dentro de una celda de Jupyter Lab, usa el signo de exclamación (!).

!python -m pydoc

pydoc - the Python documentation tool

pydoc <name> ...
    Show text documentation on something.  <name> may be the name of a
    Python keyword, topic, function, module, or package, or a dotted
    reference to a class or function within a module or module in a
    package.  If <name> contains a '\', it is used as the path to a
    Python source file to document. If name is 'keywords', 'topics',
    or 'modules', a listing of these things is displayed.

pydoc -k <keyword>
    Search for a keyword in the synopsis lines of all available modules.

pydoc -n <hostname>
    Start an HTTP server with the given hostname (default: localhost).

pydoc -p <port>
    Start an HTTP server on the given port on the local machine.  Port
    number 0 can be used to get an arbitrary unused port.

pydoc -b
    Start an HTTP server on an arbitrary unused port and open a Web browser
    to interactively browse documentation.  This option can be used in
    combination with -n and/or -p.

pydoc -w <name> ...
    Write out the HTML documentation for a module to a file in the current
    directory.  If <name> contains a '\', it is treated as a filename; if
    it names a directory, documentation is written for all the contents.

Si te fijas en la salida anterior, el primer uso de Pydoc es mostrar la documentación en texto de una función, módulo, clase, etc. Veamos cómo puedes aprovecharlo mejor que la función help.

!python -m pydoc glob

Help on module glob:

NAME
    glob - Filename globbing utility.

MODULE REFERENCE
    https://docs.python.org/3.7/library/glob

    The following documentation is automatically generated from the Python
    source files.  It may be incomplete, incorrect or include features that
    are considered implementation detail and may vary between Python
    implementations.  When in doubt, consult the module reference at the
    location listed above.

FUNCTIONS
    escape(pathname)
        Escape all special characters.

    glob(pathname, *, recursive=False)
        Return a list of paths matching a pathname pattern.

        The pattern may contain simple shell-style wildcards a la
        fnmatch. However, unlike fnmatch, filenames starting with a
        dot are special cases that are not matched by '*' and '?'
        patterns.

        If recursive is true, the pattern '**' will match any files and
        zero or more directories and subdirectories.

    iglob(pathname, *, recursive=False)
        Return an iterator which yields the paths matching a pathname pattern.

        The pattern may contain simple shell-style wildcards a la
        fnmatch. However, unlike fnmatch, filenames starting with a
        dot are special cases that are not matched by '*' and '?'
        patterns.

        If recursive is true, the pattern '**' will match any files and
        zero or more directories and subdirectories.

DATA
    __all__ = ['glob', 'iglob', 'escape']

FILE
    c:\users\hda3kor\.conda\envs\test\lib\glob.py

Ahora, extraigamos la documentación de glob usando la función help.

help(glob)

---------------------------------------------------------------------------

NameError                                 Traceback (most recent call last)

<ipython-input-13-6f504109e3a2> in <module>
----> 1 help(glob)


NameError: name 'glob' is not defined

Como ves, aparece un NameError porque glob no está definido. Para usar help y obtener la documentación, primero tendrías que importar el módulo, algo que con Pydoc no hace falta.

Exploremos ahora la función más interesante de Pydoc: ejecutarlo como servicio web.

Para ello, basta con lanzar Pydoc como script pero con el argumento -b, que inicia un servidor HTTP en un puerto libre cualquiera y abre un navegador para explorar la documentación de forma interactiva. Esto es especialmente útil cuando tienes varios servicios en marcha y no recuerdas qué puerto está libre.

!python -m pydoc -b

^C

En cuanto ejecutes la celda, se abrirá una ventana en un puerto arbitrario y el navegador tendrá un aspecto similar al siguiente.

Veamos la documentación del módulo h5py, un formato de archivo usado para almacenar los pesos de arquitecturas de redes neuronales.

Imprescindibles al documentar proyectos en Python

Independientemente del objetivo, la visión o el propósito del proyecto, la documentación suele ser bastante similar. El proyecto puede encajar en estas categorías:

• Proyecto privado (personal): puede servir para construir tu porfolio o para trabajar como freelance manteniendo un repositorio en GitHub.

• Proyectos colaborativos (en equipo): por ejemplo, un proyecto dentro de tu organización o una competición de Kaggle.

• Proyectos de código abierto: se centran en compartirse con una audiencia amplia. Esperan colaboración, contribuciones y mantenibilidad del código y la documentación a largo plazo.

Aunque las tres categorías tienen enfoques distintos, se puede reutilizar una misma plantilla de documentación en todos los casos.

Supongamos que trabajas en un proyecto open source y debes crear su repositorio en GitHub con una documentación detallada y actualizada con regularidad. Estos son los puntos clave que debes tener en cuenta:

• Archivo de requirements: muchos autores lo olvidan, pero es fundamental. Ayuda a los usuarios a reproducir tu código rápidamente. Suele ser un archivo de texto con todos los paquetes y módulos y sus versiones usados en el proyecto. También puedes indicar los requisitos en el Readme, pero tenerlos por separado es mejor: el usuario puede ejecutarlo con pip y se instalan todas las dependencias en su sistema.

• Readme: normalmente es un archivo Markdown y hace de columna vertebral del proyecto. Incluye un resumen, sus funcionalidades y su propósito, idealmente con un logotipo. Debe contener instrucciones de instalación y uso. Añade también cambios relevantes desde la versión anterior. Incluir scripts de prueba o una guía rápida para ejecutar el código con éxito desde el Readme da más confianza a quien prueba tu proyecto. También puede alertar de posibles problemas.

• Cómo colaborar: es clave, sobre todo en proyectos open source. Indica cómo pueden contribuir nuevos colaboradores: desarrollar funcionalidades, corregir bugs, mejorar la documentación, añadir tests o reportar incidencias. Incluso podrían lanzar una versión 2.0 y llevar el proyecto más lejos.

• Licencia: un archivo de texto plano que describe la licencia del proyecto. Es crucial en proyectos de código abierto: Boost, Apache, MIT, etc. Informa al usuario de si puede usarse comercialmente y con qué limitaciones.

• Asignación de tareas: si trabajas en un proyecto compartido (p. ej., Kaggle), define las tareas asignadas a cada miembro y su progreso. Ayuda a seguir el avance global.

• Reutilización de framework: es vital en proyectos compartidos (como Kaggle), donde tus compañeros pueden reutilizar lo que hayas creado y ahorrar mucho tiempo. Por ejemplo, un pipeline de preprocesamiento de datos, un script de validación cruzada, etc.

Una documentación muy recomendable, bien estructurada y que puede servir como ejemplo de cómo debería verse un proyecto open source es el repositorio de GitHub de transformers de huggingface.

Conclusión

Enhorabuena por completar el tutorial.

Un buen ejercicio es explorar un poco más el módulo Pydoc y otros formatos de docstrings de Python como Epydoc y las Google docstrings, y averiguar en qué se diferencian.

No dudes en dejar tus preguntas sobre este tutorial en los comentarios de abajo.

Referencias:

• Docstrings en Python

Si acabas de empezar con Python y quieres seguir aprendiendo, haz el curso Intermediate Python de DataCamp.