Documentation
Principes d'ingénierie logicielle en Python
Adam Spannbauer
Machine Learning Engineer at Eastman
Documentation en Python
- Commentaires
# Square the number x
- Docstrings
"""Square the number x
:param x: number to square
:return: x squared
>>> square(2)
4
"""
Commentaires
# This is a valid comment
x = 2
y = 3 # This is also a valid comment
# You can't see me unless you look at the source code# Hi future collaborators!!
Des commentaires efficaces
Commenter le « quoi »
# Define people as 5
people = 5
# Multiply people by 3
people * 3
Commenter le « pourquoi »
# There will be 5 people attending the party
people = 5
# We need 3 pieces of pizza per person
people * 3
Docstrings
def function(x):
"""High level description of function
Additional details on function
Docstrings
def function(x):
"""High level description of function
Additional details on function
:param x: description of parameter x
:return: description of return value
Page d'exemple générée à partir d'une docstring dans le paquet Flask.
Docstrings
def function(x):
"""High level description of function
Additional details on function
:param x: description of parameter x
:return: description of return value
>>> # Example function usage
Expected output of example function usage
"""
# function code
Exemple de docstring
def square(x):
"""Square the number x
:param x: number to square
:return: x squared
>>> square(2)
4
"""
# `x * x` is faster than `x ** 2`
# reference: https://stackoverflow.com/a/29055266/5731525
return x * x
Sortie d'exemple de docstring
help(square)
square(x)
Square the number x
:param x: number to square
:return: x squared
>>> square(2)
4
Passons à la pratique !
Principes d'ingénierie logicielle en Python
