La estructura de un proyecto: ejemplo Encuentro

| Publicado: | Código fuente

Un tema que se ha visto varias veces, tanto en la lista de PyAr como en la vida real, es que los desarrolladores que no estuvieron involucrados en proyectos grandes, o que sólo estuvieron metidos en uno o dos sistemas (más allá el tamaño), no saben muy bien qué estructura, o qué forma, darle a un proyecto nuevo.

Es totalmente comprensible. La estructura a tener depende de muchos factores: de la complejidad del proyecto, de cuan listo lo deja uno para empaquetarlo, de la prolijidad del desarrollador, etc.

Lo notable es que (en mi experiencia) el proyecto aunque nazca pequeño, siempre conviene que esté ordenado. Y que la forma de ordenarlo, qué estructura darle, cambia en función de las necesidades (como decía arriba) pero que siempre es bueno tener alguna.

En función de todo esto es que paso a contarles qué estructura tiene hoy Encuentro. No es la mejor del mundo, pero es la que a mí me funciona en este y otros proyectos. Y es una buena base como para que alguien que no tiene idea sepa para qué lado ir ordenando los tantos.

El código en sí lo pueden ver acá o si tienen instalado bazaar pueden hacer bzr branch lp:encuentro y exploran el código de forma local.

Bueno, a los bifes.

El código "útil" en sí

Tenemos dos archivos y varios directorios...

  • test: Este es un script que básicamente ejecuta todas las comprobaciones que necesitamos para asegurarnos que el proyecto está "verde". En el caso de encuentro, corre las pruebas de unidad (las que están en el directorio tests, ver abajo), luego corre un verificador estático de código genérico (pylint) y finalmente otro verificador puntual para pep 8.
  • version.txt: La versión del programa. La tengo separada sólo por consistencia: me gusta que esté en un sólo lado así es la misma para todos los que la necesitan (setup.py, para mostrarlo al arrancar, o cuando el usuario pide info del programa, etc).
  • bin/: Aquí (normalmente) hay un sólo archivo, con el nombre del proyecto: encuentro. Este es el script de inicio, el que arranca todo el sistema ya sea cuando lo ejecutamos desde el proyecto mismo, desde un tarball descomprimido, e incluso es el que va a parar a /usr/bin cuando se instala. Este es el único que es ejecutable, el resto del sistema son sólo módulos.
  • encuentro/: Es el directorio principal del proyecto (por eso el nombre). Acá tenemos todo el código "de producción" del proyecto, con su estructura interna. Por lo pronto, en este mismo directorio están todos los módulos que tienen que ver con el funcionamiento interno de Encuentro.
  • encuentro/ui/: Aquí tenemos todo el código que necesitamos para armar la Interfaz del Usuario del programa. También tiene que ver con el funcionamiento interno de Encuentro, pero es sólo el manejo de la interfaz. La separación de qué va aquí o qué va directamente en encuentro/ a veces es complicada.
  • encuentro/ui/media/: Todas las imágenes, audios, etc, que necesitamos para que funcione la UI en sí.
  • encuentro/logos/: También imágenes, pero que se usan como identificación del programa en sí. Aunque algunas se usan en la parte de UI, están todas acá porque también se usan en otros contextos (por ejemplo, en la instalación del paquete).
  • tests/: Los tests de unidad del proyecto, normalmente un montón de archivos cuyo nombre arranca con test_ pero también pueden haber otros (módulos o no) para dar soporte a las pruebas.

Otros directorios

Estos son directorios puntuales que tengo para Encuentro. Algunos se repiten con otros proyectos, otros no.

  • qtreactor: El módulo de integración entre Qt (el framework de interfaz gráfica que estoy usando) y Twisted (una biblioteca asincrónica que uso para trabajar con la red).
  • server: Cuando le decimos al programa "local" de Encuentro que actualice los episodios, se baja algunos archivos comprimidos de mi server, con toda la metadata. Estos archivos comprimidos se generan una vez al día a partir de los sitios webs de Encuentro, Conectate, BACUA, etc. El código para realizar todo esto está en este directorio.
  • web: Todos los archivos necesarios para montar el sitio web del proyecto.
  • windows: Imágenes, configuraciones, y explicaciones necesarias para armar el .exe en Windows y luego armar con eso el instalador final que se distribuye.

Otros archivos

Estos son otros archivos que no tienen demasiada relación entre sí, pero que son importantes en distintos momentos de la vida del proyecto:

  • AUTHORS, COPYING: Info legal: cuales son las personas que participaron del proyecto, y la licencia del mismo.
  • LEEME.txt, README.txt, AYUDA.txt: Textos de ayuda para la persona que llega por primera vez al proyecto (viéndolo desde los archivos fuente). Está en dos idiomas, pero como Encuentro es inherentemente para personas que hablan castellano, el LEEME es el que tiene la info posta.
  • anuncio.txt, pasos_release.txt: Recordatorios y textos preparados para mí (o para el que haga la release del proyecto... que vengo siendo siempre yo, :p).
  • pylintrc: Un archivo de configuración para el verificador estático de código que mencionaba arriba.
  • setup.py, MANIFEST.in: Script principal de empaquetamiento e instalación, más un archivo que podríamos decir de configuración del mismo.
  • encuentro.desktop, source_encuentro.py: Dos archivitos necesarios en sistemas Debian/Ubuntu (al menos). El primero le pasa al sistema info para poner el programa en el menú del usuario, y el otro es usado en caso de que el programa crashee, para informar automáticamente del problema.
Comentarios Imprimir