Documentatie
Software-engineeringprincipes in Python
Adam Spannbauer
Machine Learning Engineer at Eastman
Documentatie in Python
- Commentaar
# Kwadrateer het getal x
- Docstrings
"""Kwadrateer het getal x
:param x: getal om te kwadrateren
:return: x in het kwadraat
>>> square(2)
4
"""
Commentaar
# Dit is een geldig commentaar
x = 2
y = 3 # Dit is ook een geldig commentaar
# Je ziet me niet tenzij je naar de broncode kijkt# Hallo toekomstige medewerkers!!
Effectief commentaar
Commentaar 'wat'
# Definieer mensen als 5
people = 5
# Vermenigvuldig mensen met 3
people * 3
Commentaar 'waarom'
# Er zullen 5 mensen naar het feest komen
people = 5
# We hebben 3 stukken pizza per persoon nodig
people * 3
Docstrings
def function(x):
"""Hoog niveau beschrijving van functie
Extra details over functie
Docstrings
def function(x):
"""Hoog niveau beschrijving van functie
Extra details over functie
:param x: beschrijving van parameter x
:return: beschrijving van returnwaarde
Voorbeeld webpagina gegenereerd vanuit een docstring in het Flask-pakket.
Docstrings
def function(x):
"""Hoog niveau beschrijving van functie
Extra details over functie
:param x: beschrijving van parameter x
:return: beschrijving van returnwaarde
>>> # Voorbeeld gebruik van functie
Verwachte output van voorbeeld gebruik
"""
# functiecode
Voorbeeld docstring
def square(x):
"""Kwadrateer het getal x
:param x: getal om te kwadrateren
:return: x in het kwadraat
>>> square(2)
4
"""
# `x * x` is sneller dan `x ** 2`
# referentie: https://stackoverflow.com/a/29055266/5731525
return x * x
Voorbeeld docstring output
help(square)
square(x)
Kwadrateer het getal x
:param x: getal om te kwadrateren
:return: x in het kwadraat
>>> square(2)
4
Laten we oefenen
Software-engineeringprincipes in Python
