Patrones Docstring más comunes en Python

Documentar el código es un buen hábito, y los aspirantes a desarrolladores y programadores deben desarrollar el hábito de documentar su código en las primeras fases de su viaje de codificación.

Documentar un código fuente mejora la legibilidad y la gestión del código fuente y hace que sea extremadamente fácil de entender para los nuevos colaboradores del código fuente.

Las cadenas de documentos son cadenas literales escritas dentro de los códigos fuente. Actúan como comentarios o documentación para fragmentos de código. Las cadenas de documentos se utilizan para describir clases, funciones y, a veces, incluso los archivos.

En otras palabras, una cadena de documentación actúa como metadatos sobre los fragmentos de código. Una cadena de documentación contiene toda la información relevante sobre lo que están describiendo. Para una clase, contiene información sobre:

• la clase
• funciones de clase
• atributos de clase.

Para las funciones, contiene detalles sobre:

• parámetros
• tipos de datos de parámetros
• valores por defecto de los parámetros
• breves descripciones sobre los parámetros
• lo que devuelve la función
• tipo de datos de lo que devuelve la función
• errores y excepciones que plantea la función y breves descripciones sobre

Hay varios patrones de cadenas de documentos que los desarrolladores profesionales de Python usan para documentar su código.

En lugar de usar los existentes, uno puede crear su patrón docstring. Aún así, esta decisión depende únicamente del desarrollador individual o del equipo de desarrolladores.

Este artículo abordará los mejores patrones de cadenas de documentos para el lenguaje de programación Python.

Patrones Docstring en Python

Los siguientes son algunos de los mejores patrones de cadenas de documentos comúnmente utilizados en la industria por profesionales de Python.

Patrón Epytext

El patrón Epytext es un patrón docstring similar al JavaDoc. Es una parte de la herramienta Epydoc utilizada para generar documentación para los módulos de Python utilizando sus cadenas de documentación. A continuación se muestra un ejemplo del patrón Epytext.

"""
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.

@param parameter1: this is the first parameter.
@param parameter2: this is the second parameter.
@return: this is a description of what is returned by the function.
@raise KeyError: raises an exception.
@raise TypeError: raises an exception.
"""

En la parte superior se proporciona una breve descripción de la función.

Todos los parámetros de la función se escriben usando la palabra clave @param. Una explicación de lo que devuelve la función se escribe junto a la palabra clave @return.

Si la función genera errores o excepciones, se escriben utilizando la palabra clave @raise.

Patrón reST

El reSt o reStructuredText es un patrón de cadena de documentos utilizado por Sphinx, una herramienta para generar documentación para el lenguaje de programación Python. Este patrón es uno de los patrones de cadenas de documentos más utilizados en la industria de TI.

Este método también se usa como formato de salida en Pyment, una herramienta para ayudar a los programadores de Python a escribir documentación de código mejorada usando docstrings. Esta herramienta es beneficiosa cuando el código está parcialmente documentado o no contiene cadenas de documentación.

JetBrains PyCharm IDE o entorno de desarrollo integrado también utiliza el patrón reST. A continuación se muestra un ejemplo del patrón reST.

"""
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.

:param parameter1: this is the first parameter.
:param parameter2: this is the second parameter.
:return: this is a description of what is returned by the function.
:raise KeyError: raises an exception.
:raise TypeError: raises an exception.
"""

Similar al patrón de Epytext, todo es igual para este patrón, excepto que usa dos puntos o : como prefijo para las palabras clave en lugar del signo de arroba o @ en el caso del patrón de Epytext.

Una descripción concisa o completa del método se encuentra en la parte superior. Todos los parámetros se encuentran junto a la palabra clave :param. Una explicación de lo que devuelve el método se escribe junto a la palabra clave :return.

Y, los detalles sobre todos los errores se colocan junto a la palabra clave :raise.

Patrón de Google

Otro patrón en la lista es el patrón de Google. Técnicamente, su nombre no es el patrón de Google, sino que es un patrón que desarrolló Google.

Es un patrón limpio que organiza los detalles bajo los encabezados. La herramienta Sphinx también es capaz de reconocer este patrón y generar documentación.

Este patrón es uno de los patrones más docstrings también. A continuación se muestra un ejemplo del patrón de Google.

"""
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.

Args:
    parameter1: this is the first parameter.
    parameter2: this is the second parameter.

Returns:
    this is a description of what is returned by the function.

Raises:
    KeyError: raises an exception.
    TypeError: raises an exception.
"""

Al igual que los patrones anteriores, en la parte superior se encuentra una breve descripción del método.

La descripción va seguida de encabezados como Args, Returns y Raises. Bajo el encabezado Args, se colocan todos los parámetros y detalles, como su tipo y valores predeterminados.

Una descripción de lo que devuelve la función se coloca bajo el encabezado Returns. Por último, los errores o excepciones y sus detalles se escriben bajo el epígrafe Raises.

Patrón Numpydoc

El módulo numpy tiene sus patrones docstring conocidos como el patrón Numpydoc.

Este patrón es similar al patrón de Google y es reconocido por la herramienta Sphinx. Similar al patrón de Google, la información se organiza bajo encabezados.

A continuación se muestra un ejemplo del patrón Numpydoc.

"""
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.

Parameters
----------
parameter1 : int
    this is the first parameter.
parameter2 : str, "default value"
    this is the second parameter.

Returns
-------
string
    returns a string value.

Raises
------
KeyError
    raises an exception.
TypeError
    raises an exception.
"""

La descripción del método está escrita en la parte superior. Otros detalles sobre el método se organizan bajo los encabezados: Parameters, Returns y Raises.

Todos los detalles sobre los parámetros, incluido su valor predeterminado, tipo de valor, etc., se colocan bajo el encabezado Parámetros. Todos los detalles sobre lo que devuelve la función, incluido el tipo de datos, se encuentran bajo el encabezado Returns.

Por último, la información sobre los errores o excepciones y algunas descripciones se escriben bajo el encabezado Raises.