Documentation
Principes d’ingénierie logicielle en Python
Adam Spannbauer
Machine Learning Engineer at Eastman
Documentation en Python
- Commentaires
# Calcule le carré de x
- Chaînes de documentation
"""Calcule le carré de x
:param x: nombre à mettre au carré
:return: x au carré
>>> square(2)
4
"""
Commentaires
# Ceci est un commentaire valide
x = 2
y = 3 # Ceci est aussi un commentaire valide
# Vous ne pouvez pas me voir sauf si vous regardez le code source# Bonjour futurs collaborateurs !!
Commentaires efficaces
Commenter 'quoi'
# Définir personnes comme 5
people = 5
# Multiplier personnes par 3
people * 3
Commenter 'pourquoi'
# Il y aura 5 personnes à la fête
people = 5
# Nous avons besoin de 3 parts de pizza par personne
people * 3
Chaînes de documentation
def function(x):
"""Description générale de la fonction
Détails supplémentaires sur la fonction
Chaînes de documentation
def function(x):
"""Description générale de la fonction
Détails supplémentaires sur la fonction
:param x: description du paramètre x
:return: description de la valeur de retour
Exemple de page web générée à partir d'une chaîne de documentation dans le package Flask.
Chaînes de documentation
def function(x):
"""Description générale de la fonction
Détails supplémentaires sur la fonction
:param x: description du paramètre x
:return: description de la valeur de retour
>>> # Exemple d'utilisation de la fonction
Résultat attendu de l'exemple d'utilisation
"""
# code de la fonction
Exemple de chaîne de documentation
def square(x):
"""Calcule le carré de x
:param x: nombre à mettre au carré
:return: x au carré
>>> square(2)
4
"""
# `x * x` est plus rapide que `x ** 2`
# référence : https://stackoverflow.com/a/29055266/5731525
return x * x
Sortie de l'exemple de chaîne de documentation
help(square)
square(x)
Calcule le carré de x
:param x: nombre à mettre au carré
:return: x au carré
>>> square(2)
4
Passons à la pratique !
Principes d’ingénierie logicielle en Python
