Calidad

a. Principios

La programación imperativa u orientada a objetos requiere la creación de clases, instancias y funciones.

Estas tienen un comportamiento determinista que es reproducible. Dicho de otro modo, una función utilizada con los mismos parámetros de entrada produce el mismo resultado. 

He aquí un ejemplo sencillo:

>>> def cuadrado(x):  
...     return x**2  
... 

Es posible crear una prueba sobre esta función. Consiste en seleccionar una serie de parámetros y, para cada uno, el resultado esperado:

>>> def prueba_cuadrado():  
...     for x, r in {2: 4, 0: 0, -2:4}.items():  
...         if cuadrado(x) != r:  
...         print('prueba incorrecta')  
...         break  
...     else:  
...         print('prueba correcta')  
... 

b. Interpretación

Cuando se ejecuta esta función, existen dos resultados posibles. Puede que la función tenga éxito:

>>> prueba_cuadrado()  
prueba correcta 

Lo cual no significa que la función es correcta, sino que supera las pruebas previstas. La representatividad de las pruebas es, en este caso, crucial. He aquí un ejemplo:

>>> def media(valores):  
...     return sum(valores)/len(valores)  
... 

Si no se comprueba específicamente la función con una lista de valores vacía, omitimos un caso de uso. He aquí otro caso (probar [-5, 6, -1]):

>>> def balance(valores):  
...     sum([abs(n) for n in valores])/sum(valores)  
... 

Otra posibilidad es que la ejecución de la prueba sea negativa. Este caso no quiere necesariamente decir que la función no es válida. Significa, simplemente, que una de las pruebas no se ha superado. Es preciso verificar, a continuación, si se trata de un error en la función probada o de un error de la propia prueba.

He aquí un ejemplo de una función particularmente mal escrita:

>>> def seleccion(valor):   
...     if valor < 0:   
...         return 0   ...

a. Destinada a los desarrolladores

Escribir la documentación en el propio código es la mejor manera de proveer explicaciones para el lector del código.

Esto facilita la comprensión del código a cualquier persona que quiera investigarlo, lo cual resulta indispensable en un contexto de software libre. El número de aplicaciones libres que sufren una comunidad demasiado restringida debido únicamente a que el código está mal documentado es demasiado importante, y supone un riesgo para la continuidad de la aplicación libre en cuestión.

Esto sirve, a su vez, para revisar el propio código tras haber pasado a trabajar en otros proyectos.

Una de las particularidades de Python consiste en crear pruebas unitarias en la documentación (http://docs.python.org/library/doctest.html).

El procedimiento es sencillo y permite al lector hacerse una idea de qué hace el código, y puede servir como prueba unitaria minimalista.

De este modo, en Python, ya no existen comentarios de código, sino una verdadera documentación, que permite comprender el código cuando es completa y está bien realizada.

b. Destinada a los usuarios

Ayudar al desarrollador a revisar el código de su aplicación o de su librería está lejos de ser la única motivación de una buena documentación. En efecto, Python proporciona herramientas magníficas a este respecto. Para empezar, tenemos pydoc, que ofrece desde Python 3.2 una mejor presentación, y se trata de una herramienta de búsqueda rápida cuya opción -b abre un navegador:

$ pydoc modulo_prueba 

Permite visualizar la documentación de la misma manera que si hubiéramos abierto una consola y ejecutado el comando help sobre el módulo.

Existe, también, otro comando que permite generar documentación en HTML:

$ pydoc -w modulo_prueba 

El resultado es simple, pero eficaz. Para producir algo visualmente más atractivo, existe epydoc:

$ epydoc --html modulo_prueba -o path 

Se instala de la siguiente manera:

$ sudo aptitude install python-epydoc 

Permite publicar documentación sin esfuerzo alguno.