Cómo documentar el código de Python usando Docstrings

Sin la documentación adecuada, puede ser difícil comprender, mantener y depurar su código. En Python, puede usar docstrings para proporcionar descripciones concisas y ejemplos de cómo funciona el código.

¿Qué son las cadenas de documentación?

Las cadenas de documentos son cadenas que puede agregar a su código de Python para explicar qué hace y cómo usarlo. El fragmento de código puede ser un función de pitón, un módulo o una clase.

Los docstrings se parecen mucho a los comentarios estándar de Python, pero tienen algunas diferencias. Los comentarios de Python brindan información adicional a los desarrolladores sobre el funcionamiento interno del código, como detalles de implementación o advertencias a tener en cuenta al extender el código.

Por otro lado, las cadenas de documentación brindan principalmente información a los usuarios del código que no necesariamente necesitan conocer los detalles de implementación, pero deben comprender qué hace y cómo usarlo.

Cómo escribir cadenas de documentos

Por lo general, incluye cadenas de documentación al comienzo del bloque de código que desea documentar. Debe encerrarlos entre comillas triples (). Puede escribir cadenas de documentación de una línea o cadenas de documentación de varias líneas.

Las cadenas de documentación de una línea son adecuadas para código simple que no requiere mucha documentación.

A continuación se muestra un ejemplo de una función llamada multiplicar. La cadena de documentación explica que la función de multiplicación toma dos números, los multiplica y devuelve el resultado.

definitivamentemultiplicar(a, b):
Multiplica dos números y devuelve el resultado.
devolver un * segundo

Utilice cadenas de documentación de varias líneas para código más complejo que necesite documentación detallada.

Considere la siguiente clase de automóvil:

claseAuto:

 A claserepresentandoaautoobjeto.
 Atributos:
 kilometraje (flotante): el kilometraje actual del automóvil.
 Métodos:
 conducir (millas): Conduce el coche para el número especificado de millas.

definitivamente__en eso__(auto, kilometraje):
 self.kilometraje = kilometraje
definitivamenteconducir(yo, millas):

 conduce el coche para el número especificado de millas.
 Argumentos:
 millas (flotación): El número de millas para conducir.
 Devoluciones:
Ninguno

 kilometraje propio += millas

La cadena de documentación de la clase anterior describe lo que representa la clase, sus atributos y sus métodos. Mientras tanto, las cadenas de documentación del método drive proporcionan información sobre lo que hace el método, los argumentos que espera y lo que devuelve.

Esto hace que sea más fácil para cualquiera que trabaje con esta clase entender cómo usarla. Los otros beneficios de usar docstrings incluyen:

• Capacidad de mantenimiento del código: al proporcionar una descripción clara de cómo funciona el código, las cadenas de documentación ayudan a los desarrolladores a modificar y actualizar el código sin introducir errores.
• Colaboración más sencilla: cuando varios desarrolladores colaboran en la misma base de código, por ejemplo, con el Herramienta para compartir en vivo de Visual Studio—docstrings permite a los desarrolladores documentar el código de manera consistente para que todos en el equipo puedan entenderlo.
• Legibilidad de código mejorada: Docstrings proporciona un resumen de alto nivel de lo que hace el código que permite cualquier persona que lea el código para comprender rápidamente su propósito sin pasar por todo el código bloquear.

Formatos de cadenas de documentos

Una buena cadena de documentación debe describir lo que hace un fragmento de código, los argumentos que espera y los detalles de implementación si es necesario. Debe incluir especialmente cualquier caso límite que cualquiera que use el código deba conocer.

Un formato básico de docstring tiene las siguientes secciones:

• Línea de resumen: un resumen de una línea de lo que hace el código.
• Argumentos: información sobre los argumentos que espera la función, incluidos sus tipos de datos.
• Valor de retorno: información sobre el valor de retorno de la función, incluido su tipo de datos.
• Raises (opcional): información sobre cualquier excepción que la función pueda generar.

Este es solo un formato básico, ya que hay otros formatos que puede elegir para basar sus cadenas de documentación. Los más populares son Epytext, reStructuredText (también conocido como reST), NumPy y Google docstrings. Cada uno de estos formatos tiene su propia sintaxis, como se muestra en los siguientes ejemplos:

epitexto

Una cadena de documentación que sigue el formato Epytext:

definitivamentemultiplicar(a, b):

 Multiplica dos números juntos.
 @param a: El primer número a multiplicar.
 @escriba a: int
 @param b: El segundo número a multiplicar.
 @tipo b: int
 @return: El producto de los dos números.
 @rtype: int

devolver un * segundo

Texto reestructurado (resT)

Una cadena de documentación que sigue el formato reST:

definitivamentemultiplicar(a, b):

 Multiplica dos números juntos.
 :param a: El primer número a multiplicar.
 :escriba a: int
 :param b: El segundo número a multiplicar.
 :tipo b: int
 :devolver: El producto de los dos números.
 :rtipo: int

devolver un * segundo

NumPy

Una cadena de documentación que sigue el formato NumPy:

definitivamentemultiplicar(a, b):

 Multiplica dos números juntos.
 Parámetros

 a: int
 El primer número a multiplicar.
 b: int
 El segundo número a multiplicar.
 Devoluciones

 En t
 El producto de los dos números.

devolver un * segundo

Google

Una cadena de documentación que sigue el formato de Google:

definitivamentemultiplicar(a, b):

 Multiplica dos números juntos.
 Argumentos:
 a (int): El primer número a multiplicar.
 b (int): El segundo número a multiplicar.
 Devoluciones:
 int: El producto de los dos números.

devolver un * segundo

Aunque los cuatro formatos de cadenas de documentos proporcionan documentación útil para la función de multiplicación, los formatos NumPy y Google son más fáciles de leer que los formatos Epytext y reST.

Cómo incluir pruebas en las cadenas de documentación

Puede incluir ejemplos de prueba en sus cadenas de documentación utilizando el módulo doctest. El módulo doctest busca en la cadena de documentos texto que parezca sesiones interactivas de Python y luego las ejecuta para verificar que funcionan como deberían.

Para usar doctests, incluya las entradas de muestra y los resultados esperados en la cadena de documentación. A continuación se muestra un ejemplo de cómo lo haría:

definitivamentemultiplicar(a, b):

 Multiplica dos números juntos.
 Parámetros

 a: int
 El primer número a multiplicar.
 b: int
 El segundo número a multiplicar.
 Devoluciones

 En t
 El producto de los dos números.
 Ejemplos

 >>> multiplicar(2, 3)
6
 >>> multiplicar(0, 10)
0
 >>> multiplicar(-1, 5)
-5

devolver un * segundo

El Ejemplos La sección contiene tres llamadas a funciones con diferentes argumentos y especifica el resultado esperado para cada una. Cuando ejecuta el módulo doctest como se muestra a continuación, ejecutará los ejemplos y comparará la salida real con la salida esperada.

python -m doctest multiplicar.py

Si hay alguna diferencia, el módulo doctest las reporta como fallas. El uso de doctests con docstrings como este lo ayuda a verificar que el código funciona como se esperaba. Tenga en cuenta que los doctests no reemplazan a los más completos. pruebas unitarias y pruebas de integración para su código Python.

Cómo generar documentación a partir de Docstrings

Aprendió los conceptos básicos del uso de docstrings para documentar su código de Python y la importancia de una documentación de alta calidad. Para mejorar, es posible que desee generar documentación para sus módulos y funciones a partir de sus respectivas cadenas de documentación.

Uno de los generadores de documentación más populares que puede usar es Sphinx. Es compatible con el formato docstring reST de forma predeterminada, pero puede configurarlo para que funcione con el formato Google o NumPy.