Python / Documentando codigo

Bienvenidos sean a este post, hoy hablaremos sobre algo que muy pocos hacen.

En general cuando un codigo tiene variables y funciones que describen correctamente que almacenan y ejecutan respectivamente no necesitamos documentar un codigo, mas si utilizamos un comentario con una breve descripcion haria que la documentacion sea completamente innecesaria, pero siempre es recomendable hacer una documentacion sobre el codigo, en este post lo veremos de forma basica pero si quieren mas detalles sobre este tema les dejo el link de la documentacion oficial:

https://www.python.org/dev/peps/pep-0257/

La documentacion se hace con strings y por lo general se los denomina como docstrings, cualquier objeto puede ser documentado tanto en lineas multiples como en una sola linea, obviamente la de una sola linea es mas simple y ya hemos visto un ejemplo en este post, pero veamos el siguiente ejemplo:

>>> def get_nombreusuario(idusuario) :
...     """ Devuelve el nombre del usuario en base al id informado """
...     return db.get(user_id=idusuario).username
... 
>>>

Como pueden ver la documentacion de una linea la usamos para dar una breve descripcion de cual es la tarea realizada por esta funcion, su forma mas habitual es comenzar con tres comillas dobles escribir la descripcion y finalizar con tres comillas dobles nuevamente, lo bueno de trabajar de esta forma es que no necesitamos ubicarlo antes o despues de ninguna instruccion sino simplemente dentro del bloque que documentaremos, veamos el siguiente ejemplo para ver una documentacion pero con multiples lineas:

>>> def conectar(host, puerto, usuario, clave) :
...     """
...
...     Nos conecta a una base de datos directamente, para ello
...     usaremos los parametros informados al comienzo.
... 
...     :param host: El nombre o IP del host.
...     :param puerto: El puerto del host.
...     :param usuario: El usuario para la conexion
...     :param clave: La clave del usuario
... 
...     La funcion devolvera un objeto de conexion.
...     """
...     # A partir de aqui el cuerpo de la funcion.
...     return conexion
... 
>>>

Como pueden ver tambien lo comenzamos con tres comillas dobles, despues podemos escribir como queramos, siempre y cuando no cerremos las comillas, podemos usar cualquier tipo de escritura por lo general este tipo de comentarios se debe realizar al comienzo de la funcion u objeto porque de lo contrario puede dificultarnos la lectura del codigo, en este caso utilizamos la documentacion para hacer una descripcion mas profunda de la tarea que realiza y para que sirve cada parametro, por ultimo cerramos las comillas para que quede como una documentacion, despues tenemos un comentario que equivale a una documentacion de linea simple porque trabaja de la misma forma pero esta siempre comienza con un numeral (#) y no necesita ser cerrada sino que lo hara cuando presionemos Enter, el 99.9% de los programadores no lo usa para lo que se creo sino que lo utiliza para «eliminar» una linea, esto es porque tanto la documentacion como los comentarios son lineas que el lenguaje omite y no las procesa, por esta razon muchas veces los programadores por razones de seguridad o depuracion simplemente comentan una linea si no es necesaria o verificar si causa un error, por esta razon el comentario es usualmente usado de esta forma, continuando con la funcion por utimo devolvemos la conexion.

Con esto hemos cubierto lo basico de documentacion y como podemos ver esto es util para cuando trabajamos en equipo y debemos dejar el codigo que estemos trabajando y pasarlo a otra persona donde por medio de la documentacion sabra que estabamos haciendo pero como siempre eso queda completamente al criterio del programador.

En resumen, hoy hemos hablado sobre documentacion, para que esta pensado, los dos tipos que tenemos disponibles, como se implementan, tambien mencionamos a los comentarios, para que fueron pensados y para que se usan realmente, espero les haya sido util sigueme en tumblr, Twitter o Facebook para recibir una notificacion cada vez que subo un nuevo post en este blog, nos vemos en el proximo post.