Python disposa d'una característica genial anomenada string de documentació que, habitualment retallem a docstrings. Els docStrings són una eina important que hem de fer servir, ja que ajuda a millorar la documentació dels programes fent-los més fàcils d'entendre. Podem, fins i tot, obtenir el docstring d'una funció mentre el programa està en execució!
Example 7.8. Ús de DocStrings
#!/usr/bin/python # Filename: func_doc.py def printMax(x, y): '''Escriu el màxim de dos números. Els dos valors han de ser enters.''' x = int(x) # converteix a enter, si és possible y = int(y) if x > y: print x, 'és el major' else: print y, 'és el major' printMax(3, 5) print printMax.__doc__
$ python func_doc.py
5 és el major
Escriu el màxim de dos números.
Els dos valors han de ser enters.
El docstring apareix en forma de cadena a la primera línia lògica de la funció. Atenció: els docStrings també apareixeran als capítols dedicats als mòduls i a les classes.
La convenció que es segueix per escriure un docstring és un string multi-línia en el que la primera línia comença per majúscula i finalitza amb punt. A continuació, la següent línia queda en blanc i és seguida per una descripció detallada a partir de la tercera línia. És altament recomanable seguir aquesta convenció a tots els docstrings, de totes les funcions no trivials.
Podem accedir al docstring de la funció printMax fent servir l'atribut __doc__ (Atenció al doble subratllat '_') de la funció. Cal recordar que Python ho tracta tot com a objecte incloent les funcions. Veurem més respecte als objectes al capítol de classes.
Qui ha fet servir help() a Python, ja ha vist l'ús dels docstrings! El que fa aquesta instrucció és obtenir l'atribut __doc__ de la funció i mostraró d'una manera clara. Ho podem provar sobre la funció anterior simplement cal incloure help(printMax) al programa. Recordem que per a sortir de l'ajut, cal prémer q.
D'aquesta manera, la documentació dels programes poden ser obtingudes mitjançant eines automàtiques. Per tant, et recomano molt que facis servir docstrings per a tota funció no trivial que escriguis. La comanda pydoc, inclosa a la distribució de Python funciona similarment a help() fent servir els docstrings.