Documentar y probar su código al mismo tiempo, con el módulo doctest

La documentación del código es una etapa esencial durante la elaboración de un programa Python. En la empresa y en numerosos proyectos open source, documentar el código es primordial, porque este se distribuye a un gran número de desarrolladores. Es importante que el código sea claro y comprensible y una buena documentación facilita mucho esta etapa. En Python, escribir documentación requiere utilizar docstrings. Los diseñadores del lenguaje consideran los docstrings tan importantes que hay incluso una PEP que explica los estándares para escribirlos. PEP 0257 - Docstring Conventions, disponible en la dirección https://www.python.org/dev/peps/pep-0257/.

Para entender mejor para qué sirve un docstring, es útil escribir un módulo que contenga dos funciones, dos_veces y cinco_veces, que multiplique respectivamente un entero por 2 o por 5 y devuelva el resultado. Hasta ahora, los ejemplos que habíamos escrito no estaban documentados, con el objetivo de optimizar el espacio y los caracteres. Aquí, el módulo se documenta totalmente (Capitulo_4/doctest_1.py):


 1 #!/usr/bin/env python3  
 2   
 3 """ Ejemplo del libro 'Desarrollar con Python en Raspberry  
 Pi'.  
 4   
 5 Este archivo lista algunas operaciones aritméticas básicas.  
 6 """  
 7   ...
Si desea saber más, le proponemos el siguiente libro:
couv_RITRASPYT.png
60-signet.svg
Versión impresa
20-ecran_lettre.svg
Versión online
41-logo_abonnement.svg
En ilimitado con la suscripción ENI
130-boutique.svg
En la tienda oficial de ENI
Anterior
Consultar la documentación con pydoc3
Siguiente
Escritura de pruebas unitarias con el módulo unittest