3.1. Documentación de funciones

Cada función escrita por un programador realiza una tarea específica. Cuando la cantidad de funciones disponibles para ser utilizadas es grande, puede ser difícil saber exactamente qué hace una función. Es por eso que es extremadamente importante documentar en cada función cuál es la tarea que realiza, cuáles son los parámetros que recibe y qué es lo que devuelve, para que a la hora de utilizarla sea lo pueda hacer correctamente.

La documentación de una función se coloca luego del encabezado de la función, en un párrafo encerrado entre tres comillas dobles """. Así, para la función vista en el ejemplo anterior:

def hola(alguien):
    """ Imprime por pantalla un saludo, dirigido a la persona que
        se indica por parámetro. """
    print "Hola ", alguien,"!"
    print "Estoy programando en Python."

Cuando una función definida está correctamente documentada, es posible acceder a su documentación mediante la función help provista por Python:

>>> help(hola)
Help on function hola in module __main__:

  hola(alguien)
      Imprime por pantalla un saludo, dirigido a la persona que
      se indica por parámetro.

De esta forma no es necesario mirar el código de una función para saber lo que hace, simplemente llamando a help es posible obtener esta información.