Los comentarios deben ser claros y concisos, explicando cómo funciona el código o por qué se tomó una decisión específica. Los modelos generativos pueden ayudar a generar descripciones precisas mediante la ingeniería de prompts.

Ejemplo:

# Prompt sugerido para documentar un código complejo:
# "Describe el siguiente código en un lenguaje sencillo para un estudiante."

def calcular_factores(numero):
    """
    Calcula los factores de un número entero dado.

    Args:
        numero (int): El número para el cual se calcularán los factores.

    Returns:
        list: Una lista de factores del número.
    """
    factores = []
    for i in range(1, numero + 1):
        if numero % i == 0:
            factores.append(i)
    return factores

Herramientas como ChatGPT pueden generar docstrings automáticamente para funciones y clases, asegurando que la estructura de la documentación sea uniforme.

# Prompt sugerido:
# "Genera un docstring para esta función en formato Google."

def convertir_celsius_a_fahrenheit(celsius):
    """
    Convierte una temperatura de grados Celsius a Fahrenheit.

    Args:
        celsius (float): Temperatura en grados Celsius.

    Returns:
        float: Temperatura convertida a grados Fahrenheit.
    """
    return (celsius * 9/5) + 32

Además de documentar, los modelos generativos pueden sugerir ejemplos prácticos del uso de una función o clase.

Ejemplo:

# Prompt sugerido:
# "Crea un ejemplo de cómo usar esta función en un caso práctico."

def calcular_area_rectangulo(base, altura):
    """
    Calcula el área de un rectángulo.

    Args:
        base (float): La base del rectángulo.
        altura (float): La altura del rectángulo.

    Returns:
        float: El área del rectángulo.
    """
    return base * altura

# Ejemplo sugerido por la herramienta generativa:
if __name__ == "__main__":
    base = 5.0
    altura = 3.0
    print(f"El área del rectángulo es {calcular_area_rectangulo(base, altura)} metros cuadrados.")

Las herramientas generativas pueden sugerir cómo mejorar la estructura del código para hacerlo más legible, por ejemplo, separando lógica compleja en funciones más pequeñas.

Ejemplo:

# Código original:
def procesar_datos(datos):
    resultados = []
    for dato in datos:
        if dato > 10:
            resultados.append(dato * 2)
    return resultados

# Prompt sugerido:
# "Divide este código en funciones más pequeñas con nombres descriptivos."

def filtrar_datos(datos):
    return [dato for dato in datos if dato > 10]

def duplicar_datos(datos):
    return [dato * 2 for dato in datos]

def procesar_datos(datos):
    datos_filtrados = filtrar_datos(datos)
    return duplicar_datos(datos_filtrados)

Herramientas generativas pueden ayudar a crear documentación detallada para proyectos completos, como archivos README.md.

Ejemplo:

# Proyecto: Gestor de Tareas

## Descripción
Aplicación sencilla para gestionar tareas pendientes. Permite agregar, eliminar y listar tareas.

## Requisitos
- Python 3.8+

## Instalación
```bash
pip install gestor-tareas

Uso

from gestor_tareas import Gestor

gestor = Gestor()
gestor.agregar_tarea("Estudiar Python")
print(gestor.listar_tareas())

Beneficios de las herramientas generativas en la documentación