Documentación
Principios de ingeniería de software en Python
Adam Spannbauer
Machine Learning Engineer at Eastman
Documentación en Python
- Comentarios
# Eleva al cuadrado el número x
- Cadenas de documentación
"""Eleva al cuadrado el número x
:param x: número a elevar al cuadrado
:return: x al cuadrado
>>> square(2)
4
"""
Comentarios
# Este es un comentario válido
x = 2
y = 3 # Este también es un comentario válido
# No puedes verme a menos que mires el código fuente# ¡Hola futuros colaboradores!
Comentarios efectivos
Comentando 'qué'
# Definir personas como 5
people = 5
# Multiplicar personas por 3
people * 3
Comentando 'por qué'
# Habrá 5 personas en la fiesta
people = 5
# Necesitamos 3 porciones de pizza por persona
people * 3
Cadenas de documentación
def function(x):
"""Descripción general de la función
Detalles adicionales sobre la función
Cadenas de documentación
def function(x):
"""Descripción general de la función
Detalles adicionales sobre la función
:param x: descripción del parámetro x
:return: descripción del valor de retorno
Página de ejemplo generada a partir de una cadena de documentación en el paquete Flask.
Cadenas de documentación
def function(x):
"""Descripción general de la función
Detalles adicionales sobre la función
:param x: descripción del parámetro x
:return: descripción del valor de retorno
>>> # Ejemplo de uso de la función
Salida esperada del ejemplo de uso
"""
# código de la función
Ejemplo de cadena de documentación
def square(x):
"""Eleva al cuadrado el número x
:param x: número a elevar al cuadrado
:return: x al cuadrado
>>> square(2)
4
"""
# `x * x` es más rápido que `x ** 2`
# referencia: https://stackoverflow.com/a/29055266/5731525
return x * x
Salida de ejemplo de cadena de documentación
help(square)
square(x)
Eleva al cuadrado el número x
:param x: número a elevar al cuadrado
:return: x al cuadrado
>>> square(2)
4
¡Vamos a practicar!
Principios de ingeniería de software en Python
