Chaînes de documentation

Leçon 8 sur 28 du cours Clean Code - Écrire un meilleur code avec Python de Coddy.

La chaîne de documentation, ou docstring, se trouve généralement comme première instruction dans la définition d’un module, d’une fonction, d’une classe ou d’une méthode.

Déclarez une docstring en entourant la chaîne avec """ ou ''', par exemple :

def complex(real=0.0, imag=0.0):
	"""
	Forme un nombre complexe.
	
		Paramètres :
			real (float) -- la partie réelle (par défaut 0.0)
			imag (float) -- la partie imaginaire (par défaut 0.0)
	"""
    if imag == 0.0 and real == 0.0:
        return complex_zero
    ...

observez comment elle documente la fonction complex(real, imag).

Remarquez l’indentation du corps de la docstring et le """

Après avoir utilisé une docstring de cette manière, vous pouvez utiliser la propriété __doc__ pour obtenir la documentation :

complex.__doc__

produira le résultat suivant :

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

Défi

Facile

On vous donne une fonction avec un commentaire de bloc au lieu d’une docstring.

Votre tâche consiste à le remplacer par une docstring valide. Consultez le cas de test pour obtenir le bon formatage de la docstring !

Essayez vous-même

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__)