¿Cómo escribir documentación en funciones de Python?
Escribir una documentación completa y clara para tus funciones en Python no solo mejora la comprensión y el mantenimiento del código, sino que también facilita su uso por otras personas. Los "docstrings" en Python son la herramienta principal para lograr esto. Aquí te explicamos cómo crearlas adecuadamente.
¿Qué es un docstring y por qué es importante?
Un docstring es un comentario in-line utilizado para definir y explicar el propósito y funcionamiento de las funciones, módulos o métodos en Python. Siguiendo ciertas convenciones, estos comentarios son implementados usando tres pares de comillas dobles (""") y permiten que el texto se expanda en múltiples líneas.
Estructura básica de un docstring
Para escribir un docstring efectivo, se debe incluir:
Descripción breve: Indica lo que hace la función de manera concisa.
Parámetros: Define el nombre, el tipo y el propósito de cada parámetro.
Valor de retorno: Explica qué devuelve la función y su tipo de dato.
Aquí te dejamos un ejemplo ilustrativo:
defsuma(a, b):"""
Suma dos valores enteros.
Parámetros:
a (int): Primer número a sumar.
b (int): Segundo número a sumar.
Retorna:
int: La sumatoria de a y b.
"""return a + b
¿Cómo acceder a los docstrings?
Una vez definidos los docstrings, puedes acceder a ellos fácilmente. Python proporciona la función incorporada help() que muestra el docstring de una función o método especificado, así como su firma (signature).
Ejemplo de uso de help()
Supongamos que tienes la siguiente función y quieres ver su documentación:
defagregar_cinco(cualquier_parametro):"""
Añade cinco al valor del parámetro dado.
Parámetros:
cualquier_parametro (int): Un valor entero al que se sumarán cinco.
Retorna:
int: Resultado de sumar cinco al parámetro.
"""return cualquier_parametro +5
Para visualizar su docstring en la terminal, escribirías:
help(agregar_cinco)
¿Cuáles son las mejores prácticas para documentar funciones en Python?
La documentación debe ser clara, precisa y fácilmente comprensible. A continuación se presentan algunas buenas prácticas:
Sé conciso y preciso: No estás escribiendo una novela; enfócate en ser directo y claro.
Usa terminología consistente: Mantén la uniformidad en los términos descriptivos de tus docstrings.
Adapta estándares: Algunos proyectos usan estándares como Google Docstrings o reStructuredText. Asegúrate de seguir las convenciones de tu entorno de trabajo.
Recuerda que una buena documentación no solo mejora el mantenimiento sino también la colaboración entre desarrolladores.
Continúa explorando y comentando otras técnicas y lenguajes de programación en los que estás interesado para mejorar continuamente tus habilidades en documentación de código. ¡Sigue aprendiendo y codificando!
Recordar que en Python se maneja la indentación para delimitar bloques de instrucciones.
Escribir los programas los más simple posible.
Comentar los programas, explicando el propósito, funcionamiento completo y el resultado
esperado.
Al inicio de cada función, agregar brevemente un comentario que explique el comportamiento
general de la función.
Definir el nombre de funciones, variables y constantes que mejor representen el contenido que
almacenarán.
No usar variables cuyo nombre carezca de significado descriptivo. Con un código legible y
nombres significativos, el código se va auto documentado.
Declarar variables en líneas separadas, posibilitando agregar una descripción de cada variable
mediante comentarios.
Definir el nombre de funciones, módulos y clases que mejor representen las acciones que
realizan.
Definir el tamaño de las sangrías para que sean regulares (consistentes) y no varíen a lo largo
del código, es decir, si el primer bloque ocupa como indentación una tabulación, el resto de
bloques deben ser indentados con una tabulación adicional por cada nivel, con eso se facilita la
lectura en cualquier editor de código.
Ser consistente al momento de utilizar un estándar para nombres largos, por ejemplo para una
variable que almacena cantidad de alumnos 'contador_alumnos'
Comentar cuando sea justo y necesario, usar los comentarios dentro de las funciones para
describir las variables (sólo cuando su utilidad sea potencialmente dudosa) y cuando existan
bloques de código difíciles de entender a primera vista; el exceso de comentarios vuelve ilegible
el código.
Definir variables locales al inicio de la implementación de cada función, como un bloque de
código bien separado del bloque que contenga las instrucciones ejecutables, ésta separación
puede consistir en una línea en blanco, o bien un comentario que denote la utilidad de cada
bloque.
Evitar la incorporación de más de una instrucción por línea. Esto reduce notoriamente la
legibilidad del código, ya que el programador habitualmente está acostumbrado a leer una
instrucción por línea.
Realizar la indentación necesaria, si una instrucción abarca más de una línea.
Les comparto una publicación excelente sobre buenas practicas con Python.
++Thomas Cokelaer - Ejemplo sobre cómo documentar sus cadenas de documentos en Python
++
++¿Cuáles son las buenas prácticas para escribir Documentación dentro de Python?++
Casi tan importante como la escritura de código, es su correcta documentación, una parte fundamental de cualquier programa que a menudo se infravalora o simplemente se ignora. Aparte de los comentarios entre el código explicando cómo funciona, el elemento básico de documentación de Python es el Docstring o cadena de documentación. Simplemente es una cadena de texto con triple comillas que se coloca justo después de la definición de función o clase que sirve de documentación a ese elemento.
Además de esta documentación básica, lo correcto es detallar mejor en el Docstring qué hace y cómo se usa la función o clase y los parámetros que necesita. Se recomienda usar el estilo de documentación del software de documentación sphinx, que emplea reStructuredText como lenguaje de marcado.
Ejemplo de una función bien documentada:
En este ejemplo de la función power() de numpy no solo se explica qué hace la función, sino que indica los parámetros de entrada y salida e incluso da algunos ejemplos de uso.
Lo mejor que pueden hacer es aprender a hacer la documentación desde que comienzan a aprender programación. si no, luego se acostumbran a nunca hacerlo y les terminará costando más trabajo algo que a final de cuentan tienen que aprender sí o sí.
///<summary>///Lee la configuración de la aplicación desde el disco.///</summary>///<return>///Devuelve true si la configuración fue leida. Si hubo algún error se devuelve false.///</return>///<param name="archivo">///Ruta del archivo en disco a leer.///</param>
En Python para el tema de comentario sugieren no máximo de 72 caracteres.
Consulta, que diferente hay en documentar con """ y #?
En la uni aprendo Java y la manera de documentar dentro del código es mediante el uso de
/** Descripción del método
*@params@return
*
*
Así, se puede especificar por ejemplo que hace un método, que parámetros recibe, qué retorna y si es que lanza alguna excepción. Luego mediante javadoc, una utilidad de Oracle, se genera la documentación contenida en un HTML y es ahí donde uno puede ver mediante links como usar ese método.
En Python las buenas practicas indicadas por PEP8 indican que un comentario inicializado con # no debería tener mas de 72 caracteres. También resulta interesante agregar los pasos a seguir para resolver un problema, agregar una descripción con docstrings o simplemente una linea que explique que hace el código.
Recuerden que también podemos utilizar el # para hacer comentarios de una línea y el """ para hacer comentarios de varias líneas.
Para la documentación es necesario ser:
Conciso y preciso
Explicar los parámetros
Lo que regresa la función
las comillas simples triples ' ' 'tambien sirven para comentar nuestro código.
🔴 Aquí mi apoyo con los docstrings 🔴
.
Imagen 1: 🥝 Diseño cool
Imagen 2: 🎨 Como se ve en la consola (Windows Terminal)
Imagen 3: 💿 El codigo para copiar
.
🍬 Los y las invito a que prueben metiendo una funcion dentro del help o con el .doc
.
.
.
def operacion(x, y):"""Suma los valores de dos valores.Recordemos que x & y son parametros
y que 5 y 17 son argumentos.No, no son lo mismo.Los parametros son los que se ponen
al definir(def) la funcion.En cambio los argumentos son el
numero, nombre, o dato que va a
suplir al parametro en la operacion a
la hora de imprimir.Parametros: x recibe un numero entero
y recibe un numero entero
Que regresa? #Resultado pues
returns el valor de x mas y
"""
return x + y
print("\n") #La \n da un salto de linea al imprimir
print(operacion(5,17))print("\n") #La \n sirve para separar 'prints'print(operacion.__doc__)help(operacion)
🍖 Windows + . = Así agregan emojis a cualquier lugar.
