Lo Básico para Empezar con Python – Comentarios y Documentación

A medida que nuestras aplicaciones crecen, se vuelve mas complicado saber cual es el objetivo de cierta función o el correcto uso de un parámetro etc. De ahí la importancia de los comentarios y la documentación de código.

Los comentarios y la documentación de código, son bastante importantes en el mundo de programación, aunque muchos desarrolladores indican que puntualmente para el caso de los comentarios en el código, que si es necesario ponerlos, quiere decir que tu código no esta bien escrito. Puede que esta afirmación sea verdad en la medida de que si escribimos un buen código, debería ser bastante descriptivo el nombramiento de clases, métodos, variables, etc. Pero no está de mas el uso de estos en el proceso de desarrollo que que siempre vamos a necesitar por ejemplo un #TODO: Hay que hacer tal cosa, y los comentarios nos van a facilitar la vida en este sentido, pero si pasamos a producción, estos comentarios no deberían existir.

En cuanto a la documentación, es un caso totalmente diferente a los comentarios, puesto que es bastante importante la documentación, ya que esta es la que va a aparecer en los autocomplete de nuestro editor, en los asistentes de consola, etc. Y tener documentado es un requisito para poder generar un código de alta calidad. La forma de documentar varía según el lenguaje, y el día de hoy, vamos a enfocarnos puntualmente en el caso de Python.

Comentarios

Los comentarios en Python son simples líneas informativas donde vamos a colocar información temporal y no interpretable en tiempo de ejecución. Realmente no hay mucho que decir, simplemente que todo comentario comienza con el simbolo #, y de esta manera entonces un comentario seria de la siguiente manera:

Los comentarios se pueden usar para “comentar” código, valga la redundancia, es decir que podemos inhabilitar una línea de código que no queremos borrar, pero no deseamos que se ejecute, hay que tener en cuenta que los comentarios no deben ser usados para describir controles de cambios, para esto existen los repositorios git o svn o lo que use; el resultado del anterior código seria:

wmachuca @ wmachucamac in ~/Python/1.HolaMundo [10:57:02]
python holamundo.py
Hola Mundo
I Am Wil

Documentación o Docstrings

Los docstrings en Python, se identifican de manera que se escriben dentro de triple comillas dobles “““ Ejemplo de Docstring ”””, esta documentación es una manera muy eficiente para poder asociar documentación puntualmente a módulos, clases, métodos y funciones, y se preguntarán ¿Que querrá decir cuando dice que puntualmente?, pues sencillo, si en un programa documentamos todos los elementos del archivo (modulo, clases, métodos y funciones), es posible solicitar por consola la documentación puntual de un método, o de una clase.

¿Como se Escribe la Documentación?

La documentación en Python, igual que la programación es necesario definirla por medio de la jerarquía, por ejemplo, si queremos poner la documentación  al módulo, solo podremos la documentación al inicio del archivo, si es una clase, lo pondremos dentro de la clase, a la altura de identación de código dentro de la clase, y así mismo, aplica para métodos y funciones. Los docstrings, se verán de la siguiente manera:

Es verdad que la documentación es algo que es una tarea tediosa, pero es necesaria para hacer software escalable, y si desarrollamos servicios o API, es aun más importante, por que puede usarlo cualquier persona. Y algo que hay que saber es que siempre la documentación debe estar en ingles, por que no sabemos quien venga a hacer mantenimiento a nuestro código y no sabemos que idioma habla, puede hablar finlandes, chino, o un idioma por allá de africa que ni idea y si le escribimos la documentación en nuestro idioma, pues se jodieron por que no les va a servir para nada. Igualmente para con el nombramiento de variables, metodo, clases y módulos (Eso es un tip ;)).

¿Como se Lee la Documentación?

Para el tema de como acceder a esta documentación simplemente debemos hacerlo, importando el archivo en la consola de Python, y escribiendo el metodo help(), y enviando como parametro que documentación es la que necesitamos.

Para nuestro archivo, vamos a solicitar toda la documentación que tengamos disponible en nuestro módulo, simplemente nos posicionamos en la carpeta y hacemos lo siguiente en la consola:

wmachuca @ wmachucamac in ~/Python/2.Doctrings [11:55:37]
python
Python 2.7.10 (default, Oct  6 2017, 22:29:07)
[GCC 4.2.1 Compatible Apple LLVM 9.0.0 (clang-900.0.31)] on darwin
Type “help”, “copyright”, “credits” or “license” for more information.
>>> import docstrings
>>> help(docstrings)

Este comando help(), nos enviará como resultado, toda la documentación que encuentre en nuestro archivo, dandonos como resultado la siguiente ventana, con la documentación que nosotros escribimos.

Help on module docstrings:
NAME
    docstrings
FILE
    /Users/wmachuca/Python/2.Doctrings/docstrings.py
DESCRIPTION
    Este es el docstring del modulo que estamos desarrollando,
    y es la vista general de todo lo que esta aca contenido
CLASSES
    __builtin__.object
        MyClass
    class MyClass(__builtin__.object)
     |  Esta es la documentacion de la clase, que se trabaja,
     |  y si contiene parametros para inicializar deberian estar
     |  descritos en estas lineas.
     |  :param object: descripcion del parametro
     |
     |  Methods defined here:
     |
     |  my_method(my_param)
     |      En metodos funciona de la misma manera
     |      :param my_param: descripcion del parametro
     |
     |  ----------------------------------------------------------------------
     |  Data descriptors defined here:
     |
     |  __dict__
     |      dictionary for instance variables (if defined)
     |
     |  __weakref__
     |      list of weak references to the object (if defined)
FUNCTIONS
    my_function()
        Y una funcion pero sin parametros
(END)

Si deseamos un resultado mas puntual, de un metodo o una funcion simplemente vamos accediendo en detalle separando por jerarquías, es decir si queremos acceder a la documentacion de la clase, solo escribimos help(docstrings.MyClass), o si queremos ver la función escribiremos help(docstrings.my_function), pero si queremos acceder en el ejemplo a la documentación del metodo, sera necesario acceder jerarquicamente a este, veamos el ejemplo.

wmachuca @ wmachucamac in ~/Python/2.Doctrings [13:45:38]
python
Python 2.7.10 (default, Oct  6 2017, 22:29:07)
[GCC 4.2.1 Compatible Apple LLVM 9.0.0 (clang-900.0.31)] on darwin
Type “help”, “copyright”, “credits” or “license” for more information.
>>> import docstrings
>>> help(docstrings.MyClass.my_method)
Help on method my_method in module docstrings:
my_method(my_param) unbound docstrings.MyClass method
    En metodos funciona de la misma manera
    :param my_param: descripcion del parametro
(END)

Un ejemplo de muy buenas practicas de documentación en Python que me encontré navegando en internet, es ese ejemplo que hace Thomas Cokelaer en este ejemplo de documentación en Python (https://thomas-cokelaer.info/tutorials/sphinx/docstring_python.html):

Bien y con esto dejo este tema de Python que me parece básico para continuar con camino de aprendizaje de Python. Cualquier comentario o necesidad de ayuda, pueden dejarlas en la caja de comentarios. Y como ya saben, I Am Wil y esta es la web de un programador ;).

Puedes compartirlo en:
Share on Facebook
Facebook
Tweet about this on Twitter
Twitter
Share on LinkedIn
Linkedin
Share on Google+
Google+