Documentation Strings

Lección 8 de 28 del curso Clean Code - Write better code using Python de Coddy.

La cadena de documentación o docstring aparece principalmente como la primera instrucción en la definición de un módulo, una función, una clase o un método.

Declara el docstring envolviendo la cadena con """ o ''', por ejemplo:

def complex(real=0.0, imag=0.0):
	"""
	Forma un número complejo.
	
		Parámetros:
			real (float) -- la parte real (por defecto 0.0)
			imag (float) -- la parte imaginaria (por defecto 0.0)
	"""
    if imag == 0.0 and real == 0.0:
        return complex_zero
    ...

observa cómo documenta la función complex(real, imag).

Observa la indentación del cuerpo del docstring y de """

Después de usar el docstring de esta forma, puedes utilizar la propiedad __doc__ para obtener la documentación:

complex.__doc__

Mostrará lo siguiente:

Form a complex number.
	
	Parameters:
		real (float) -- the real part (default 0.0)
		imag (float) -- the imaginary part (default 0.0)

Desafío

Fácil

Se te proporciona una función con un comentario de bloque en lugar de una cadena de documentación.

¡Tu tarea es reemplazarlo por una cadena de documentación válida y revisar el caso de prueba para lograr el formato correcto de la cadena de documentación!

Pruébalo tú mismo

def sum_binary(a, b):
    # Calculate sum of two integers in binary formmated string
    # Parameters:
    # a (int) -- Integer number
    # b (int) -- Another integer number
    # Returns:
    # binary_sum (str) -- The sum of a and b in binary format
    sum = a + b
    binary_sum = bin(sum)
    return str(binary_sum)[1:] # Final formmating

print(sum_binary.__doc__)