Code is more often read than written

– Guido Van Rosssum

El código es mas veces leído que escrito, por eso es importante documentarlo apropiadamente. Un código bien documentado permite a quien recibe el código saber que hace dicho pedazo de código, sea una función, una clase, modulo o paquete.

Quien recibe el código puede ser tal vez un compañero de trabajo, puede ser alguien que no conozcas en absoluto o puedes ser tu mismo dentro de unos cuantos meses.

Estoy seguro que no te será extraña la vez que viste un código y pensaste que está mal escrito, que hay cosas que le cambiarías y después te das cuenta que fuiste tu quien lo escribió.

Si estas usando algún módulo, te darás cuenta de lo importante que es la documentación, buscarás ejemplos, querrás saber que parámetros y que tipos de datos recibe alguna función, que clase debes extender para hacer tu trabajo mas sencillo. Si el paquete/modulo que estas pretendiendo usar no está bien documentado es muy probable que desistas de usarlo.

Comentar vs Documentar

“Una cosa es una cosa y otra cosa es otra cosa”, antes de avanzar mas tenemos que entender la diferencia de las dos. En general comentar es describir tu código, la audiencia esperada son otros desarrolladores encargados de mantener tu código. Los comentarios ayudan al lector a entender que hace el código.

El codigo te dice como; los comentarios te dicen por que.

– Jeff Atwood (Coding Horror)

Documentar es describir el uso y la funcionalidad  a los usuarios finales, desarrolladores tal vez, pero no son los encargados de mantener el código, no necesitan ver el código, necesitan usarlo.

Para comentar el código en Python usaremos el símbolo de “gato” o “número”

def hello_world():
    # Un comentario precediendo a una llamada a print
    print("Hello world")

De acuerdo al PEP8 los comentarios deben tener máximo 72 caracteres. Pero si por alguna razón lo que tratas de explicar es demasiado largo entonces puedes usar múltiples lineas.

def hello_world():
    # Esta es un comentario demasiado largo como para que 
    # entre en una sola linea, por eso lo ponemos en 2
    print("Hello world")

Comentar el código tiene múltiples propósitos:

• Planear y revisar: cuando estas desarrollando nuevo código te puede servir para que no olvides porque hiciste algo en una función determinada, o que paso sigue después de ejecutar cierto código.

# Paso 1
# Paso 2
# Paso 3

• Describe el código. Los comentarios pueden explicar la intención de ciertas partes del código.

# Intento de conectarse usando las configuraciones previas, 
# En caso de no poder, solicitar datos al usuario.

• Descripción algoritmica. Puedes indicar por que usas cierto método en lugar de otro, a veces es mejor legibilidad que rendimiento, a veces es mejor lo contrario.

# Usando quick sort porque es mas rápido.

• Etiquetado: El uso de etiquetas para saber que debe corregirse, mejorarse en el código es muy común y buena práctica.

# TODO: Agregar condición cuando val es None

Algunas de las convenciones al escribir comentarios:

1. Mantén los comentarios lo mas cercano del código que estas comentando
2. No uses formato complicado, como tablas ASCII o figuras, es mejor el texto plano.
3. No uses información redundante, asume que el lector tiene conocimientos básicos para entender el programa.
4. Diseña tu código para que se “comente” a si mismo”, la forma mas fácil de entender el código es leerlo.

Documentando el código

Ahora que ya sabemos que es comentar el código, vamos a ver que es documentar el código.

Cada función, método o clase puede tener documentación, en el caso de Python es una cadena de comillas simples, dobles o triples definida justo debajo del nombre de la función/método o clase y tienen por nombre “docstrings”

Este “docstring” es accesible vía la propiedad __doc__o usando la función helpen alguna clase.

>>> help(str):
Help on class str in module __builtin__:

class str(basestring)
| str(object='') -> string
|
| Return a nice string representation of the object.
| If the argument is a string, the return value is the same object.
|
| Method resolution order:
| str

La documentación provista por help incluye las funciones y parámetros requeridos por cada una de ellas, proviene de la introspección de dicha clase, el texto justo debajo de la definición de clase el la documentación explicita en la propiedad __doc__y la podemos ver usando la función dir:

>>> dir(str)
['__add__', '__class__', '__contains__', '__delattr__', '__doc__',

Entonces, lo podemos imprimir:

>>> print(str.__doc__)
str(object='') -> string

Return a nice string representation of the object.
If the argument is a string, the return value is the same object.

Dicha propiedad es inmutable en objetos dentro de __builtins__ aunque puede ser modificado en otros objetos.

Tipos de docstrings.

Un docstring puede contener una o varias lineas, a diferencia de los comentarios que requieren el símbolo de “gato” o “numero” aquí, al ser una cadena, podemos usar la misma sintaxis que con las cadenas:

def func():
    "Docstring de una sola linea con comillas dobles"

def func2():
    'Docstring con comillas sencillas' 

def func3():
    """Resumen
    
    Docstring con comillas triples, aqui como en las cadenas
    puedo hacer uso de multiples lineas, asi puedo dar mejor
    formato a la documentación"""

Notaron que en el ultimo hay un “resumen” y un resto de comentario?. No es obligatorio, digo, no pasa nada sin no seguimos dicho formato, pero por convención lo debemos hacer, la primera linea resume todo en una sola sentencia, después podemos explicarnos.

Documentación de Paquetes y Módulos

Los paquetes y módulos tambien pueden tener documentación, en el caso de los paquetes se escribe al principio del archivo __init__.py y en el caso de los módulos se escribe al principio de dicho módulo.

De la misma forma que con el docstring de las funciones o clases, se pueden usar comillas simples, dobles o triples.

Finalizando

Comentar y documentar el código debe ser regla de oro para cualquier desarrollador, tanto para hacer el código mas fácil de entender y usar para otros como para salvar el pellejo cuando algo no ande bien y quieres saber rápido que fue lo que pretendías hace unos meses o años atras.

Es fácil y te sirve de mucho, incluso hay herramientas como sphynx, que puede crear la documentación de tus proyectos usando los docstrings y la introspección del código.

[amazon_link asins=’1449355730,1449357016,9351198146,1449340377′ template=’ProductCarousel’ store=’launocom-20′ marketplace=’MX’ link_id=’aaf50b37-9686-11e8-ba7e-654ecae9cfb6′]

---

Si te gustó el articulo, compártelo en tus redes sociales, si tienes algo que agregar con toda confianza hazlo en los comentarios.