C贸mo Documentar El C贸digo Python

Fecha de publicaci贸n: 29 Noviembre 2021
Tiempo de lectura: 5 min.
Premium: False
N煤mero de visitas: 353


Algo que muchas y muchos desarrolladores pasamos por alto, es sin duda es 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.

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.

Docstring

Lo primero que debemos saber es que en Python existen 2 formas en las cuales podemos comentar nuestro c贸digo.

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

Podemos documentar nuestro c贸digo ya sea con el car谩cter numeral (#) o con triple comillas simples (''') o triple comillas doble("""). Aunque lo habitual ser谩 con triple comillas doble. 馃

Ejemplos.

# Comentario de una sola l铆nea

'''
Comentario con m煤ltiples l铆neas.
Al utilizar comillas simples podemos utilizar comillas "dobles".
'''

"""
Comentario con m煤ltiples l铆neas.
Al utilizar comillas dobles podemos utilizar comillas 'simples'.
"""

Ahora, 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 etc.. Lo haremos mediante triple comillas simples o triple comillas dobles.

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

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

Para ello vamos a colocar un comentario con triple comillas simples, o dobles, en la primera l铆nea del cuerpo de la funci贸n.

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煤sculas 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 tipo de comentarios los conoceremos como docstring (documentation string) 馃

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):
    """Retorna Verdadero o Falso si el par谩metro 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.

Podemos confirmar esto de 2 formas distintas.

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.

class User():
    """
    El objeto user contiene los siguientes atributos:
    - username
    - email
    """

    def __init__(self, username, email):
        """Permite inicializar un nuevo usuario

        Args:
            username (string): Username
            email (string): Correo electronico
        """
        self.username = username
        self.email = email

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):
    """Retornar Verdadero o Falso si el par谩metro 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

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, 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
"""

T煤 por supuesto 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.

M谩s Tips y Ejercicios 馃悕

Adquiere una subscripci贸n PyWombat por tan solo $3 USD. al mes.

Conoce los beneficios de ser usuario premium:
Niveles desbloqueados: Ten accesos a todos los niveles de ejercicios. 馃敁
Nuevo l铆mite: Incrementa tu l铆mite de ejercicios por semana. 馃殌
Contenido 煤nico: Recibe semanalmente recursos exclusivos de Python (Videos, Art铆culos y Capitulos del libro PyWombat, comienza como desarrollador Python. 馃悕