Tips y trucos

Documentación

Es importante mantener documentado nuestro código, tanto entre las lineas de código pero tambien en las funciones, a veces aunque tratamos de poner un nombre descriptivo a la función muchas veces esto no ayuda mucho. Para esto cada función en Python puede contar con una documentación.

Para esto podemos poner, justo abajo de la definición y dentro del bloque de código una cadena que será el docstring :

def mifuncion():
    "Esta función es solo de ejemplo"
    # El coding va acá

Y ahora esa cadena esta disponible a cualquiera que ocupe la función para saber que hace la función. para acceder a este valor basta con poner el nombre de la función y sin poner paréntesis poner un punto y luego __doc__ , es decir mifuncion.__doc__ .

def division(numero, divisor, veces=0):
    "Realiza una division haciendo restas y recursion"
    if divisor > numero:
        return veces, numero
    rest = numero - divisor
    return division(rest, divisor, veces = veces+1)

print division.__doc__
Realiza una division haciendo restas y recursion

Es el deber del desarrollador explicar lo relacionado a la función:

• Que hace la función
• Que parámetros espera (cuantos y de que tipo)
• Que valor devuelve
• En caso de manejar errores, que valores devuelve en caso del error
• En caso de lanzar Excepciones (lo veremos luego, lo prometo), que excepciones se lanzan?

Pero… todo eso en una sola linea?. No con calma, las cadenas en Python pueden estar en diferentes lineas, pero sobre todo pueden usar tres comillas para definir cadenas que tienen retornos de carro. por ejemplo:

def division(numero, divisor, veces=0):
    """Realiza una division haciendo restas y recursion
    Parametros:
    * numero: Numero entero
    * divisor: Numero divisor
    * veces: Numero de veces que se ha llamado esta funcion

    Devuelve una tupla, el primero valor es el numero de veces 
    que se ha llamado la funcion (numero de veces que divisor 
    cabe en numero) y un residuo.
    """
    if divisor > numero:
        return veces, numero
    rest = numero - divisor
    return division(rest, divisor, veces = veces+1)

print division.__doc__
Realiza una division haciendo restas y recursion
    Parametros:
    * numero: Numero entero
    * divisor: Numero divisor
    * veces: Numero de veces que se ha llamado esta funcion

    Devuelve una tupla, el primero valor es el numero de veces
    que se ha llamado la funcion (numero de veces que divisor
    cabe en numero) y un residuo.

Y si no hay documentación?

A veces usamos funciones que no tienen documentación, para este caso les recomiendo usar la función help, esta función nos mostrará los parámetros que se reciben y si hay parámetros con valores por defecto.

Al menos así no iremos tan a ciegas.

helptambien aplica a clases, modelos y paquetes.

Ultimas notas sobre funciones

• Evita las funciones muy largas, si una función es muy larga, tal vez deberías cortarla en partes mas pequeñas.
• Una función debe hacer una sola acción y debe hacerla bien. Si tu función realiza varias tareas entonces debe dividirse en mas funciones.
• Preferiblemente una función debe devolver un valor de retorno. Al menos para indicar a quién le llamó si todo fue bien o si hubo algún error. Habrá casos también, en que un valor de retorno es innecesario.
• Siempre pon documentación a tus funciones
• Siempre que actualices tus funciones actualiza la documentación también.
• Así como con las estructuras de datos, si pasas un objeto como parámetro a una función estás pasando una referencia a dicho objeto, si lo modificas en la función el cambio aplica para todo aquel que tenga referencia a dicho objeto.

---

Si te gusta el tutorial, por favor mándame un mensaje, mi twitter: @markuzmx , tal vez te gustó tanto que prefieras hacer una donación via paypal la cantidad tu la pones ? Gracias por apoyarme.

You must be logged in to take the quiz.