Especificaciones del código

¿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:

1. Descripción breve: Indica lo que hace la función de manera concisa.
2. Parámetros: Define el nombre, el tipo y el propósito de cada parámetro.
3. Valor de retorno: Explica qué devuelve la función y su tipo de dato.

Aquí te dejamos un ejemplo ilustrativo:

def suma(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:

def agregar_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!