Estructura de proyectos simples

Introducción

La organización del código es una parte crucial para cualquier proyecto, especialmente en ciencia y programación. Un buen diseño de estructura permite a los desarrolladores mantener la claridad y coherencia del código, lo que facilita la colaboración y el mantenimiento a largo plazo. En este artículo, exploraremos cómo organizar proyectos simples utilizando Python, enfocándonos en la creación de una estructura modular y fácilmente manejable.

Explicación principal con ejemplos

Una buena estrategia para organizar los proyectos es seguir el patrón de "Estructura de Carpetas Clásica" (Directory Structure Classic), que divide el código en carpetas según su funcionalidad. Aquí te presentamos un ejemplo basado en la unidad 5 del curso:

proyecto/
├── data/            # Carpeta para los datos
│   └── raw/         # Subcarpeta con datos originales
│   └── processed/   # Subcarpeta con datos procesados
├── src/             # Carpeta principal del código fuente
│   ├── __init__.py  # Inicializa el paquete
│   ├── main.py      # Script principal que ejecuta el programa
│   ├── utils.py     # Funciones útiles y auxiliares
│   ├── models/      # Subcarpeta para clases y modelos
│   └── scripts/     # Scripts adicionales, como test o script de preparación de datos
├── tests/           # Carpeta para pruebas unitarias
│   └── __init__.py  # Inicializa la carpeta de pruebas
│   └── test_main.py # Prueba del script principal
├── docs/            # Documentación del proyecto
├── requirements.txt # Dependencias necesarias
└── README.md        # Archivo inicial con información general y instrucciones

En este ejemplo, src es el directorio principal donde se encuentra todo el código. main.py es un script que ejecuta la lógica principal del programa. utils.py contiene funciones auxiliares, mientras que models/ puede contener clases y modelos más complejos. La carpeta scripts puede alojar scripts adicionales como tests o preparación de datos.

Ejemplo de código

A continuación, se muestra un ejemplo simplificado de cómo podrían verse las partes principales del main.py, utils.py y models/:

# main.py
from src import utils, models

def run():
    data = utils.load_data()
    model = models.Model(data)
    result = model.predict()
    utils.save_result(result)

if __name__ == "__main__":
    run()

# utils.py
import json

def load_data():
    with open("data/processed/data.json", "r") as file:
        return json.load(file)

def save_result(result):
    with open("output/result.txt", "w") as file:
        file.write(str(result))

# models/__init__.py
from .model import Model

# models/model.py
class Model:
    def __init__(self, data):
        self.data = data

    def predict(self):
        # Lógica para predecir resultados basada en el modelo
        return "Prediction"

Errores típicos / trampas

1. Falta de __init__.py: Es común que se olviden los archivos __init__.py, que inicializan las carpetas como paquetes y permiten importar submódulos.

1. Subcarpetas innecesarias: Crear demasiadas subcarpetas puede complicar la estructura y hacerla menos legible. Solo crea una carpeta cuando sea necesario para agrupar funcionalidades similares.

1. Carpeta de datos sin estructura: No organizar adecuadamente los datos puede resultar en confusiones y dificultades al buscar archivos específicos, especialmente con proyectos que crecen en tamaño.

1. Falta de tests: Olvidarse de incluir una carpeta para pruebas unitarias y no escribir tests puede llevar a problemas desconocidos en el futuro.

Checklist accionable

• [ ] Asegúrate de tener un archivo __init__.py en cada carpeta que desees importar como un paquete.
• [ ] Organiza las subcarpetas según la funcionalidad y evita crear demasiadas carpetas innecesarias.
• [ ] Separar los datos en carpetas raw, processed, etc., para mantenerlos organizados.
• [ ] Incluye una carpeta tests con pruebas unitarias para cada script o módulo relevante.
• [ ] Documenta el proyecto con un archivo README.md y asegúrate de incluir dependencias en requirements.txt.

Cierre

En resumen, organizar proyectos de manera efectiva es crucial para mantenerlos limpios y escalables. Siguiendo estas sugerencias, podrás crear una estructura sólida que facilitará el mantenimiento y colaboración a largo plazo.

Siguientes pasos

• Aprender más sobre paquetes Python: Familiarízate con la creación de paquetes y cómo distribuirlos.
• Profundizar en pruebas unitarias: Mejora tus habilidades en escritura de tests para asegurar que tu código funcione correctamente.
• Explorar frameworks y bibliotecas científicas avanzadas: Una vez que hayas dominado la organización básica, podrías querer explorar herramientas más avanzadas como NumPy, Pandas o Matplotlib.

¡Esperamos que esta guía te haya sido útil para organizar tus proyectos de manera efectiva!