En el desarrollo, algo que muchas veces pasamos por alto, es sin duda el tema de la documentación.

Y seamos sinceros, hasta cierto punto es comprensible. En la mayoría de los casos lo que más deseamos, y en lo que nos enfocamos, es en plasmar nuestra solución y en que el programa funcione correctamente, y no en tener que redactar la documentación pertinente 😜

Sin embargo hay que tener en cuenta que un código legible y bien documentado será siempre mucho más fácil de leer y sobre todo mantener, por lo tanto es indispensable saber cómo documentar nuestro código de forma correcta.

Es por ello que, para este post, aprenderemos a documentar nuestro código Python, para que no sólo nuestro yo del futuro nos lo agradezca, si no también nuestro equipo de trabajo.

Es un tema muy interesante, y al cual no dudo que le podrás sacar mucho provecho, así que te invito a que te quedes.

Bien, sin más dilación comencemos.

Comentarios

Antes de entrar de lleno con el tema me gustaría hiciéramos un rápido repaso de como podemos comentar nuestro código en Python.

Ojo, comentar nuestro código no es sinónimo de documentar nuestro código, pero es necesario hacer el repaso.

Si recordamos existen 3 formas de hacero.

Podemos documentar nuestro código ya sea con el carácter numeral (#), con triple comillas simples (''') o triple comillas doble("""). 🧐

Ejemplos.

# Comentario de una sola línea

'''
Al utilizar triple comillas dobles podremos
añadir saltos de línea a nuestro comentario.

Al utilizar comillas simples podemos utilizar comillas "dobles".
'''

"""
Al utilizar triple comillas dobles podremos
añadir saltos de línea a nuestro comentario.

Al utilizar comillas dobles podemos utilizar comillas 'simples'.
"""

Docstring

Con todo esto en mente, siempre que nosotros deseemos documentar nuestro código, ya sea una función, un método, una clase, un módulo o un paquete, lo haremos mediante el docstring.

Veamos.

Comencemos con algo sencillo. Documentamos la siguiente función.

def palindromo(sentencia):
    sentencia = sentencia.lower().replace(' ', '')
    return sentencia == sentencia[::-1]

Para poder documentar nuestro código vamos a colocar, en la primera línea del cuerpo de la función, un comentario con triple comillas simples, o tiple comillas dobles. Por convención será triple comillas dobles.🔥

Este comentario deberá cumplir con los siguientes puntos.

• La primera línea debe poseer una breve descripción del funcionamiento del código.
• Las descripciones deben comenzar con mayúscula y finalizar con punto.
• Si existen más líneas, la segunda deberá ser un espacio en blanco, de tal forma que sea fácil distinguir entre la descripción y el resto del comentario.
• Las siguientes líneas deben ser uno o más párrafos que describan las convenciones de llamada del objeto.

A este de comentario los conoceremos como docstring (documentation string) 🤓 Un comentario con triple comillas dobles, o simples, en la primera línea del bloque del objeto.

Mediante este comentario seremos capaces de asociar la documentación al objeto pertinente.

Para este ejemplo, la función pudiera quedar de la siguiente manera.

def palindromo(sentencia):
    """Permite conocer si un str es, o no, un palíndromo."""

    sentencia = sentencia.lower().replace(' ', '')
    return sentencia == sentencia[::-1]

Un docstring bastante sencillo.

Una vez el intérprete de Python reconozca que la primera línea de la función es un docstring, almacenará este comentario en el atributo __doc__ del objeto. En este caso en el atributo __doc__ de la función (Recordemos que en Python todo es un objeto).

Podemos acceder a la documentación de 2 formas diferentes.

Ya sea accediendo directamente al atributo.

>>> palindromo.__doc__
'Retornar Verdadero o Falso si el parámetro es, o no, un palíndromo.'

O utilizando la función help.

>>>help(palindromo)
palindromo(sentencia)
    Retornar Verdadero o Falso si el parámetro es o no un palíndromo

Como puedes observar, el uso del docstring permite un mayor contexto sobre el funcionamiento de nuestro código, claro, siempre y cuando la documentación sea clara y precisa.

Y ahora, quizás te estés preguntado ¿Qué tipo de objetos podemos documentar utilizando el docstring? La respuestas es bastante sencilla, podemos documentar funciones, métodos, clases y módulos. A estos objetos en Python los conoceremos como objetos documentables, y todos ellos, por supuesto, cuentan con el atributo doc.

Aquí un par de ejemplos.

"""Módulo Main"""

class User(object):
    """Representa un usuario.

    Attributes:
        username (str): [Username]
        password (str): [Password]
    """

    def __init__(username: str, password: str) -> None:
        """Inicializa en objeto de tipo User.

        Args:
            username (str): [Username]
            password (str): [Password]
        """

        self.username = username
        self.password = password



def palindromo(sentence: str) -> bool:
    """Permite conocer si un string es, o no, un palindromo.

    Args:
        sentence (str)

    Returns:
        bool
    """
    sentence = sentence.lower().replace(' ', '')
    return sentence == sentence[::-1]

Testear nuestro código

Listo, ya sabemos documentar nuestro código ¿Y ahora qué? bueno, déjame decirte que las bondades de los docstring no terminan aquí, ya que con este tipo de comentarios seremos capaces de testear nuestro código. Si, así lo como lo lees, podemos testear nuestro código Python mediante comentarios. 🤯

Para ello basta con definir los casos de pruebas dentro del docstring.

Veamos un ejemplo.

def palindromo(sentencia):
   """Permite conocer si un str es, o no, un palíndromo.

    Examples
    --------
    >>> palindromo('Anita lava la tina')
    True

    >>> palindromo('Se van sus naves')
    True

    >>> palindromo('PyWombat')
    False
    """

    sentencia = sentencia.lower().replace(' ', '')
    return sentencia == sentencia[::-1]

Para este ejemplo he definido 3 casos de pruebas para mi función palíndromo.

Para poder testar nuestra función a partir del docstring, basta con utilizar el módulo doctest de Python. 🕵️‍♀️

En la consola ejecutaremos la siguiente sentencia.

python -m doctest <MODULO>.py

En mi caso el archivo tiene por nombre main,py.

python -m doctest main.py

Si queremos un mayor contexto con respecto a las pruebas haremos uso de la bandera -v.

python -m doctest main.py -v

El módulo doctest tomará todos los objetos documentables del archivo y ejecutará las pruebas a partir de los correspondientes docstring. ⚔

Si todas las pruebas fueron exitosas no deberíamos tener ninguna tipo de salida en consola, sin embargo, si alguna prueba llegará a fallar una excepción será lanzada.

Ejemplo.

Failed example:
    palindromo('PyWombat')
Expected:
    False
Got:
    True
**********************************************************************
1 items had failures:
   1 of   3 in main.palindromo
***Test Failed*** 1 failures.

Como podemos observar, a través del módulo doctest, seremos capaces de testear nuestro código utilizando únicamente el intérprete de Python, sin la necesidad de instalar ningún tipo de dependencia externa, pudiendo así conocer qué partes de nuestro código funcionan, o no, correctamente.

¿Bastante cool no lo crees? 😎

Esto por supuesto lo podemos aplicar para el N número de funciones y métodos de nuestro código.

Formatos

Perfecto, ya sabemos tanto documentar cómo testear nuestro código, así que ¿Ahora qué? Bueno, ya para ir finalizando este post, hablemos sobre los tipos de formato que podemos implementar en nuestros docstrings.

Es importante mencionar que no existe como tal un estándar a seguir, sin embargo sí existen un par de formatos propuestos por la comunidad que podemos utilizar. 🤠

Aquí los más populares.

• Google Docstrings

"""
This is an example of Google style.

Args:
    param1: This is the first param.
    param2: This is a second param.

Returns:
    This is a description of what is returned.

Raises:
    KeyError: Raises an exception.
"""

• reST

"""
This is a reST style.

:param param1: this is a first param
:param param2: this is a second param
:returns: this is a description of what is returned
:raises keyError: raises an exception
"""

• Epytext

"""
This is a javadoc style.

@param param1: this is a first param
@param param2: this is a second param
@return: this is a description of what is returned
@raise keyError: raises an exception
"""

Por supuesto, tú puedes elegir el que más te agrade y se adapte a tus necesidad, o, inclusive, utilizar tu propio formato.

Lo importante aquí es siempre seguir un estándar, y seguir documentando nuestro código con el mismo formato con el que lo hemos hecho con anterioridad. 🍻

Conclusión

En conclusión, para nosotros poder documentar nuestro código de forma correcta lo mejor que podemos hacer es utilizar docstrings, comentarios creados utilizando triple comillas simples, o dobles, que van a encontrarse en la primera línea de nuestras funciones, métodos, clases o módulos.