Si no documentas tu código en Python, te arriesgas a ser maldecido por futuros desarrolladores, quienes tratarán de descifrar qué diablos estabas haciendo. Además, si no documentas tu código, ¿cómo sabrás qué estás haciendo tú mismo? ¡Incluso podrías pasar semanas intentando recordar cómo funciona tu propio código!. Así que, como ves la documentación en Python es fundamental.

La documentación también te ayuda a ganarte amigos en el mundo de la programación. Si documentas bien tu código, los demás desarrolladores te amarán, te idolatrarán y querrán colaborar contigo en todos los proyectos que emprendas. Pero si no lo haces, te convertirás en un paria de la comunidad de Python, desterrado a los confines más oscuros del repositorio de código.

Por último, si no documentas tu código, estás condenado a la miseria. Tus errores te perseguirán para siempre, y nunca podrás encontrar la causa raíz de los problemas. En cambio, si documentas tu código, podrás encontrar y solucionar errores más rápido que el mismísimo Flash.

En conclusión, documentar tu código en Python es crucial si quieres tener amigos, evitar maldiciones y vivir una vida feliz y libre de errores. ¡Así que no lo subestimes!

Mejora tus desarrollos en Python. Documentación.

En Python, hay varias formas de documentar el código para que sea más legible y fácil de entender. A continuación, te presento tres formas comunes de documentar el código en Python:

• Comentarios: Los comentarios son una forma simple de documentar tu código en Python. Puedes agregar comentarios a tu código usando el símbolo #. Los comentarios son ignorados por el intérprete de Python, lo que significa que no afectan el funcionamiento del código, pero son muy útiles para explicar lo que está sucediendo en el código.
• Docstrings: Los docstrings son cadenas de texto que se encuentran en la parte superior de una función, clase o módulo en Python. Estas cadenas de texto se utilizan para describir el propósito de la función, clase o módulo. Los docstrings son especialmente útiles porque se pueden acceder a ellos mediante la función help() de Python, lo que hace que sea muy fácil para otros desarrolladores entender cómo funciona tu código.
• Anotaciones de tipo: Las anotaciones de tipo son otra forma de documentar el código en Python. Las anotaciones de tipo se utilizan para especificar el tipo de los argumentos y el valor de retorno de una función. Esto hace que sea más fácil para otros desarrolladores entender cómo se supone que se debe usar una función y qué tipo de datos debe recibir y devolver.

¿Como comentar en Python?

Los comentarios comienzan con el símbolo # y se extienden hasta el final de la línea.

A continuación, te presento algunos ejemplos de cómo agregar comentarios en Python,

# Esto es un comentario en una línea

Puedes agregar comentarios en la misma línea de código, después de la instrucción correspondiente,

x = 5 # Asignamos el valor 5 a la variable x

También puedes agregar comentarios multilínea utilizando comillas triples,

"""
Esto es un comentario multilínea que
abarca varias líneas de código. Aquí puedes
agregar notas más largas y detalladas.
"""

Es importante comentar tu código de manera clara y concisa para que otros desarrolladores puedan entender fácilmente lo que está sucediendo en el programa. En general, se recomienda comentar las partes más complejas del código, los puntos clave o las decisiones importantes que se toman. Además, es una buena práctica escribir comentarios descriptivos para las funciones y clases, explicando lo que hacen y cómo se deben utilizar.

Las mejores prácticas a la hora de comentar en Python

• Usa comentarios para explicar el «por qué» en lugar del «qué»: En lugar de simplemente explicar lo que hace una línea de código, es mejor enfocarse en por qué se está haciendo eso. De esta manera, otros desarrolladores podrán entender mejor el propósito del código y podrán modificarlo en el futuro si es necesario.
• Comenta las partes complejas del código: Si estás escribiendo un código complejo, asegúrate de agregar comentarios para explicar los detalles importantes. Esto puede ayudar a otros desarrolladores a entender mejor cómo funciona el código y facilitar su mantenimiento.
• Usa nombres de variables y funciones descriptivos: Utiliza nombres de variables y funciones que sean descriptivos y expliquen su propósito. De esta manera, el código será más fácil de leer y entender para otros desarrolladores.
• Agrega comentarios para las funciones y clases: Si estás escribiendo una función o una clase, asegúrate de agregar comentarios que expliquen su propósito y cómo se deben utilizar.
• Evita comentarios redundantes: Trata de evitar comentarios redundantes que simplemente repitan lo que ya está claro en el código. En su lugar, enfócate en agregar comentarios que expliquen detalles importantes o que aclaren por qué se está haciendo algo de una determinada manera.
• Usa un estilo de comentario consistente: Utiliza un estilo de comentario consistente en todo el código, ya sea que utilices comentarios en línea o comentarios multilínea. De esta manera, el código será más fácil de leer y entender para otros desarrolladores.

Docstrings

¿Que son los Docstrings en Python?

En Python, los docstrings son cadenas de texto que se utilizan para documentar las funciones, módulos y clases. Los docstrings se colocan en la primera línea después de la definición de la función, módulo o clase y se encierran en comillas triples («»» «»» o »’ »’).

Los docstrings son una forma de documentación incorporada en Python y se utilizan para proporcionar información sobre la funcionalidad y el propósito de una función, módulo o clase. Los docstrings son opcionales, pero se recomienda encarecidamente su uso ya que pueden ayudar a otros desarrolladores a entender y utilizar tu código.

Aquí hay un ejemplo de un docstring en una función en Python,

def suma(a, b):
    """
    Esta función toma dos números y devuelve su suma.

    Args:
        a (int): El primer número para sumar.
        b (int): El segundo número para sumar.

    Returns:
        int: La suma de los dos números.
    """
    return a + b

En este ejemplo, el docstring proporciona información sobre los argumentos que se deben pasar a la función y lo que la función devuelve. También incluye una breve descripción de lo que hace la función.

Es importante destacar que los docstrings son accesibles a través de la función help() en Python. Al llamar a help() con el nombre de una función, módulo o clase, se mostrará su docstring. Por ejemplo,

help(suma)

Esto mostrará el docstring de la función suma en la consola.

¿Como utilizar los docstrings?

Existen varios formatos para escribir docstrings en Python. A continuación, te presento los tres formatos más comunes:

• Formato de una sola línea: Este formato se utiliza para docstrings cortos que se ajustan en una sola línea. Se escriben entre comillas triples en la misma línea que la definición de la función o módulo. Ejemplo,

def saludar(nombre: str) -> str:
    """Esta función recibe un nombre y devuelve un saludo personalizado."""
    return f'Hola, {nombre}!'

• Formato de varias líneas: Este formato se utiliza para docstrings más largos que no se ajustan en una sola línea. Se escriben en varias líneas, cada una de ellas entre comillas triples, y deben comenzar con una breve descripción en la primera línea, seguida de una línea en blanco y luego detalles adicionales sobre la función o módulo. Ejemplo:

def suma(a: int, b: int) -> int:
    """
    Esta función toma dos números enteros y devuelve su suma.

    Argumentos:
        a (int): El primer número para sumar.
        b (int): El segundo número para sumar.

    Devuelve:
        int: La suma de los dos números.
    """
    return a + b

• Formato de reST (reStructuredText): Este formato utiliza la sintaxis de reStructuredText, que es un lenguaje de marcado para escribir documentación. Se utiliza en docstrings más largos y detallados, y permite incluir títulos, subtítulos, listas, tablas y otros elementos de formato. Ejemplo:

def calcular_area(base: float, altura: float) -> float:
    """
    Esta función calcula el área de un triángulo rectángulo.

    :param float base: La base del triángulo.
    :param float altura: La altura del triángulo.

    :returns: El área del triángulo.
    :rtype: float
    """
    return (base * altura) / 2

¿Como utilizar los docstring con módulos, clases, métodos, variables y funciones?

Para utilizar los docstrings en módulos, clases, métodos, variables y funciones en Python, se siguen las mismas convenciones generales que se utilizan para las funciones. A continuación, te presento algunos ejemplos de cómo se pueden utilizar los docstrings en diferentes elementos de Python:

• Módulos: El docstring de un módulo se coloca en la parte superior del archivo y se escribe entre comillas triples. Este docstring se utiliza para proporcionar información general sobre el módulo. Ejemplo,

"""
Este es un módulo de ejemplo que contiene algunas funciones útiles.
"""
def funcion_ejemplo():
    """
    Esta es una función de ejemplo que no hace nada.
    """
    pass

• Clases: El docstring de una clase se coloca en la primera línea después de la definición de la clase y se escribe entre comillas triples. Este docstring se utiliza para proporcionar información sobre la clase y su uso. Ejemplo,

class ClaseEjemplo:
    """
    Esta es una clase de ejemplo que no hace nada.
    """
    def __init__(self):
        pass

• Métodos: El docstring de un método se coloca en la primera línea después de la definición del método y se escribe entre comillas triples. Este docstring se utiliza para proporcionar información sobre el método y sus argumentos. Ejemplo,

class ClaseEjemplo:
    def metodo_ejemplo(self, argumento1, argumento2):
        """
        Este es un método de ejemplo que no hace nada.

        Args:
            argumento1: Descripción del argumento 1.
            argumento2: Descripción del argumento 2.
        """
        pass

• Variables: El docstring de una variable se coloca en la línea anterior a la definición de la variable y se escribe entre comillas triples. Este docstring se utiliza para proporcionar información sobre el propósito y uso de la variable. Ejemplo,

"""
Este es un módulo de ejemplo que contiene algunas variables útiles.
"""
variable_ejemplo = 42
"""
Esta es una variable de ejemplo que contiene el valor 42.
"""

• Funciones: El docstring de una función se coloca en la primera línea después de la definición de la función y se escribe entre comillas triples. Este docstring se utiliza para proporcionar información sobre la función y sus argumentos. Ejemplo,

def funcion_ejemplo(argumento1, argumento2):
    """
    Esta es una función de ejemplo que no hace nada.

    Args:
        argumento1: Descripción del argumento 1.
        argumento2: Descripción del argumento 2.

    Returns:
        Descripción del valor de retorno.
    """
    pass

¿Cuales serían las mejores prácticas a la hora de utilizar los docstrings en Python?

• Utilizar comillas triples: Los docstrings se escriben entre comillas triples («»»), ya que esto permite que el docstring abarque varias líneas.
• Empezar con una descripción breve: El docstring debería empezar con una descripción breve del elemento que se está documentando, seguida por una línea en blanco.
• Detallar los argumentos y valores de retorno: En el caso de funciones, métodos y constructores, es importante detallar los argumentos que acepta y el valor que devuelve.
• Utilizar el formato correcto: Existen diferentes formatos que se pueden utilizar para los docstrings en Python, como por ejemplo, el formato de Google, el formato de numpy, entre otros. Es importante elegir el formato adecuado y utilizarlo de manera coherente en todo el código.
• Ser consistente: Es importante ser consistente al utilizar los docstrings en todo el código. Por ejemplo, se debería utilizar el mismo formato en todas las funciones y métodos.
• Mantener el docstring actualizado: El docstring debería mantenerse actualizado a medida que el código evoluciona. Si se realizan cambios significativos en una función o método, es importante actualizar el docstring correspondiente.
• Utilizar lenguaje claro y conciso: El docstring debería utilizar un lenguaje claro y conciso, evitando tecnicismos innecesarios.
• No repetir información obvia: El docstring no debería repetir información obvia que ya se encuentra presente en el código. Por ejemplo, no hace falta explicar qué hace una función si su nombre ya indica claramente su función.
• Utilizar ejemplos: En algunos casos, puede ser útil incluir ejemplos en el docstring para ilustrar el uso de la función o método.
• Documentar el módulo: Además de documentar las funciones y métodos, es importante documentar también el módulo en sí, proporcionando información general sobre su uso y funcionalidad.

¿Que son las anotaciones de tipo en Python?

Las anotaciones de tipo en Python son una característica introducida a partir de la versión 3.5 del lenguaje, que permite especificar el tipo de datos esperado para los parámetros y valores de retorno de una función o método.

Las anotaciones de tipo se escriben utilizando una sintaxis especial que consiste en colocar el nombre de la variable o parámetro, seguido de dos puntos y el tipo de datos esperado. Por ejemplo, si se quiere especificar que un parámetro de una función debe ser una cadena de texto, se podría escribir lo siguiente,

def saludo(nombre: str) -> str:
    return "Hola " + nombre

En este ejemplo, la anotación nombre: str indica que se espera que el parámetro nombre sea una cadena de texto (string), mientras que la anotación -> str indica que la función devuelve una cadena de texto.

Es importante tener en cuenta que las anotaciones de tipo en Python no afectan al comportamiento de la función en sí, sino que son simplemente una ayuda para la legibilidad del código y para detectar posibles errores de tipo durante la ejecución del programa. Es decir, Python seguirá permitiendo el uso de valores de tipos diferentes a los especificados en las anotaciones, aunque esto no se recomienda ya que puede llevar a errores inesperados.

Las anotaciones de tipo también son útiles para mejorar la documentación del código y para facilitar el trabajo en equipo, ya que permiten a otros programadores entender más fácilmente cómo se deben utilizar las funciones y métodos en un proyecto.

¿Como utilizar las anotaciones de tipo en Python?

Para utilizar las anotaciones de tipo en Python, se sigue la siguiente sintaxis,

def nombre_funcion(parametro: tipo) -> tipo_retorno:
    # Código de la función
    return valor_retorno

Donde:

• nombre_funcion es el nombre de la función que se está definiendo.
• parametro es el nombre del parámetro de la función, seguido de dos puntos y el tipo de dato esperado.
• tipo es el tipo de dato que se espera para el parámetro.
• tipo_retorno es el tipo de dato que devuelve la función.
• valor_retorno es el valor que devuelve la función.

Por ejemplo, para definir una función que recibe dos parámetros de tipo entero y devuelve un valor de tipo entero, se podría utilizar la siguiente sintaxis,

def suma(num1: int, num2: int) -> int:
    resultado = num1 + num2
    return resultado

¿Que tipos existen en Python y como utilizarlos en las anotaciones?

En Python, existen varios tipos de datos que se pueden utilizar en las anotaciones de tipo, algunos de los mas utilizados son los siguientes,

• int: para números enteros.
• float: para números decimales.
• bool: para valores booleanos True o False.
• str: para cadenas de texto.
• list: para listas de elementos de cualquier tipo.
• tuple: para tuplas de elementos de cualquier tipo.
• dict: para diccionarios con pares clave-valor de cualquier tipo.
• set: para conjuntos de elementos de cualquier tipo.
• Any: para indicar que se acepta cualquier tipo de dato.
• Union: para indicar que se acepta uno de varios tipos de datos.

Por ejemplo, para definir una función que recibe un parámetro de tipo entero y otro de tipo cadena de texto, y devuelve un valor de tipo booleano, se podría utilizar la siguiente sintaxis,

def funcion_ejemplo(num: int, texto: str) -> bool:
    if len(texto) > num:
        return True
    else:
        return False

En este ejemplo, se utiliza int y str como tipos de datos para los parámetros num y texto, respectivamente, y bool como tipo de dato para el valor de retorno de la función.

Es importante destacar que las anotaciones de tipo no son restricciones estrictas, y Python seguirá permitiendo el uso de valores de cualquier tipo como parámetros de entrada y salida. Las anotaciones de tipo son simplemente una ayuda para la legibilidad del código y para detectar posibles errores de tipo durante la ejecución del programa.

El vídeo

Lo mismo que te he contado hasta el momento pero en formato vídeo,

---