You are currently browsing the tag archive for the ‘organizar ficheros en directorios’ tag.

En el artículo “Como organizar ficheros en carpetas” ya he descrito criterios a tener en cuenta a la hora de crear las carpetas de un proyecto informático. En este artículo quiero dar un ejemplo real con comentarios de como se pueden organizar las carpetas en el caso concreto de una aplicación en C++. Aunque se trata de un caso concreto, aporta muchas ideas que se pueden generalizar.

Presento las carpetas en formato de árbol. Es el formato habitual para mostrar una estructura de carpetas, sin embargo aleja mucho los elementos principales de la carpeta raíz que, por lo tanto, se ven más difícilmente en su conjunto. Sin embargo, creo que será suficiente tener este problema en mente.

Los nombres propuestos para cada carpeta aparecen en cursiva. Están en inglés, pero se pueden cambiar según conveniencia. Los nombres de las carpetas usan el guión bajo ‘_’ en lugar de espacios para nombres compuestos por varias palabras. Conviene no usar espacios en las rutas de ficheros, ya que pueden complicar el procesamiento.

Todo lo relacionado con el proyecto se encuentra en una carpeta raíz.

  • cfg: Ficheros de configuración cuyos contenidos dependen de la máquina en que corre el programa. Normalmente sólo habrá uno que contiene información como la dirección IP o el nombre del equipo en la red. Se debería guardar un fichero de configuración por defecto en la carpeta code.
  • code: La carpeta que contiene los ficheros fuentes y es la carpeta raíz para un control de versiones.
    • mi_lib: Cada biblioteca tiene su propia carpeta. El nombre de la carpeta se ajusta lógicamente a lo que hace la biblioteca. Conviene usar un nombre corto que puede usarse como prefijo en los nombres de los ficheros fuentes. También es posible sólo añadir el directorio code a la ruta de inclusiones y incluir los ficheros mediante una ruta relativa como #include "mi_lib/include/mi_cabecera.h". En Java, las carpetas deben tener el nombre del paquete a que corresponden.
      • doc: Ficheros de documentación y tutoriales a compilar junto con la documentación de los ficheros de código por el sistema de documentación automático. La documentación en esta carpeta completa el manual de referencia creado a partir de los ficheros fuente del programa.
      • include: Ficheros de inclusión y otros ficheros públicos.
      • lib: Ficheros “cpp” en C++ u otros ficheros privados. También es habitual llamar esta carpeta src. Yo prefiero no usar este nombre ya que todo dentro de la carpeta code es “source”. De hecho, la carpeta code se podría llamar source.
    • main: Para el programa principal también hay una carpeta. Esta tiene la misma estructura que las demás. En lugar de main se puede usar el nombre del programa como nombre de carpeta. Si tengo varios ejecutables, entonces conviene tener una carpeta main en cuya subcarpeta doc se encuentra la documentación del proyecto y donde se hace referencia a todos los ejecutables y bibliotecas del proyecto – en fin sobre todas las subcarpetas de la carpeta code.
      • cfg: Una carpeta adicional para el programa principal puede ser una carpeta con ficheros patrones para la configuración de la máquina. Estos ficheros se copian a la carpeta cfg y se modifican para la máquina del programador.
    • project: Esta es la carpeta contiene los ficheros creados por el IDE. Cuando añades la carpeta code al control de versiones deberás borrar algunos ficheros no fuentes creados por el IDE. Los nombres de estos ficheros son diferentes para cada IDE.
      • Eclipse: Se usas varios IDE, entonces crea una subcarpeta para cada uno. Eclipse sería un nombre adecuado para el IDE Eclipse. Puede haber otros nombres como NetBeans o VisualStudio. Si no te gustan los entornos gráficos puedes crear una carpeta makefile para ser usado desde una consola.
  • compiled: Todos los ficheros generados. La idea es poder borrar el contenido de esta carpeta por completo para hacer “limpieza”.
    • generated_doc: Documentación generada por sistema de documentación automáticos.
      • html: Esta carpeta crea doxygen para el formato HTML. Habrá más carpetas para otros formatos de documentación como LaTeX.
    • gcc: Una carpeta para cada compilador que se usa. Si sólo uso un compilador, entonces este nivel de carpeta no es necesario.
      • Debug: El compilador de C++ suele crear una carpeta para cada configuración. Una suele llamarse “Debug” y otra “Release”. Puede haber más carpetas para más configuraciones; por ejemplo para enlaces con diferentes bibliotecas.
        • exe: La carpeta de ejecutables contiene todos los ficheros binarios necesarios para utilizar el programa compilado. Puede haber ficheros de configuración por defecto que meramente se necesitan copiar. ¡Incluye esta copia en el makefile! Para una aplicación java, se puede considerar usar el nombre jar en lugar de exe.
        • obj: Ficheros intermedios creado por el compilador y no necesarios para la ejecución del programa. En Java, esta carpeta podría denominarse class.
  • ext: Bibliotecas externas. Cada componente tiene una carpeta propia. Es importante archivar la biblioteca externa junto con el proyecto, ya que una versión más moderna quizá no funcionará con el código propio. Para reducir el uso del disco duro puede ser útil guardar las bibliotecas externas físicamente en una carpeta común y hacerlas aparecer en la carpeta ext mediante un enlace (soft link) del sistema operativo (con el comando ln en Unix.)
  • io: Carpeta principal para ficheros temporales y de entrada y salida del programa. Se entiende que se pueden borrar todos estos ficheros sin perjuicio al funcionamiento del programa. En un entorno real, las subcarpetas de io pueden encontrarse en otros directorios. Esto se debería poder ajustar con los ficheros en la carpeta cfg. Para hacer pruebas sin ensuciar al resto del disco duro, se aprovecha la carpeta io dentro de la carpeta raíz del proyecto. Para archivar un proyecto no haría falta guardar los ficheros dentro de la carpeta io – sólo la estructura de los directorios.
    • in: Ficheros de entrada al sistema. Es la responsabilidad del programa de borrar los ficheros procesados.
    • out: Fichero de salida del sistema.  Es la responsabilidad del programa de no sobrescribir ficheros todavía no procesados. No es su responsabilidad de borrarlos, ya que esto haría el sistema que recibe los ficheros. En un sistema real, la carpeta out sería la carpeta in del sistema siguiente.
    • temp: Ficheros temporales del programa. Es la responsabilidad del programa de borrar los ficheros. Es la responsabilidad del programador que sólo el programa deja sus ficheros ahí y que pueda limpiar la carpeta con un simple “borra todo”.
    • trace: Conviene tener una carpeta especial para trazas.
  • documentation: Documentación que ni es generada ni un código fuente para un sistema de documentación automatizado. Estos son ficheros Word, Excel, PDF, imágenes, emails y cualquier otro editado y procesado por una mente humana.
    • emails: Correos electrónicos con el cliente y otras personas involucradas. No guardes todos los emails aquí. Sólo aquellos que documentan cambios en los demás documentos.
    • manuals: Manuales de usuario o de referencia editado por un ser humano. Aquellos creados por un un sistema de documentación automático se encuentran en la subcarpeta generated_doc de la carpeta compiled.
    • specification: La especificación del proyecto. Para proyectos grandes es importante separar la especificación de otra documentación ya que los ingenieros de prueba usan meramente la especificación para comprobar que un software cumple los requisitos.

Por la longitud del artículo se nota que la creación de un árbol de carpetas para un proyecto no es trivial. Aún así todavía faltan carpetas que pueden ser importantes como una web_doc_root para un proyecto de páginas web. Pero, en fin, es sólo un ejemplo.

Referencias

Anuncios

Una decisión que afecta a todo un proyecto informático es como se organizan los ficheros en carpetas. Esto es por una parte una cuestión de gusto, pero por otra muchas veces una afectada por necesidades técnicas. Así la conclusión más importante es que no hay una forma idónea de organizar los ficheros en directorios. Sólo hay formas más o menos malas. En este artículo queremos repasar qué asuntos hay que tener en cuenta a la hora de crear las carpetas. Hay otro artículo con un ejemplo de un árbol de carpetas.

La estructura de directorios es una de las tareas iniciales de un proyecto. Conviene pensársela bien, porque cambiarla más tarde puede ser complicado. Igualmente importante son los nombres de las carpetas (y ficheros).

Es preferible usar nombres cortos, pero sobre todo significativos y comprensibles. Ficheros y carpetas cuyos nombres no contienen espacios son más fácilmente manejables por una línea de comandos y URLs. Separa palabras con guión bajo en lugar de espacios.

No utilices nombres de fichero con mayúsculas, ya que pueden causar problemas entre Unix y Linux, que distinguen entre mayúsculas y minúsculas, y Microsoft Windows que no lo distingue. Además, cualquier combinación de minúsculas o mayúsculas puede ser fácilmente convertida a sólo minúsculas (o mayúsculas). Algo útil a la hora de convertir palabras de búsqueda o argumentos de la línea de comando a ficheros.

La palabra “proyecto” se usa de forma ambigua. Un proyecto por parte de la empresa (y tu trabajo) es un conjunto de aplicaciones que debes programar. Sin embargo, cada aplicación se llama “proyecto” en tu editor, mientras el conjunto de todos estos proyectos se llama “solución” o “workspace” según el editor. Aquí usamos la palabra “proyecto” en el sentido de la empresa, es decir, tu carpeta raíz de proyecto se refiere a un workspace en tu IDE. Cada aplicación se llamará “subproyecto” o “aplicación”.

Hay muchos criterios a tener en cuenta a la hora de crear la estructura de directorios. Aquí viene una colección no completa.

  • En general es preferible tener a todos los carpetas por debajo de un directorio raíz del proyecto. Esto no siempre es posible. En sistemas Linux se distribuyen diferentes ficheros a carpetas de sistema diferentes – como “include” o “lib”. O una parte de los ficheros estará en un web host. Considera la posibilidad de mantener todos los ficheros por debajo del directorio raíz y copiarlos con un shell script a su destino final. Esto puede ser un paso de post-compilación.
  • Si  una parte de los ficheros será pública – en un web host o un API dentro  una carpeta “include”, entonces el proyecto ya debería tener esta estructura. Idealmente se podría copiar la carpeta pública al servidor host con un solo comando. Por ejemplo, todos los ficheros que estarán en el servidor web se encuentran en una carpeta “web_document_root”.
  • Separa las carpetas bajo control de versiones de las que no. No mezcles código fuente con ficheros generados. Aunque no te quedes sólo con los ficheros fuente cuando archives el proyecto. Quizá no funcionará el compilador en diez años. (Y ya verás como diez años pasan…)
  • Separa bien subproyectos para evitar dependencias. Una biblioteca podría servir para otro proyecto y debería estar claro de que más subproyectos depende.
  • Guarda bibliotecas externas en una carpeta especial. Conviene quedarse con el nombre de la biblioteca y la versión, por ejemplo “boost_1_42_0” para la versión 1.42.0 de la biblioteca Boost. Es importante saber la versión y tener la posibilidad de tener varias versiones de la biblioteca externa integradas en el proyecto. Nunca sabes cuándo adaptas tu código a la nueva versión de la biblioteca y si adaptas todo o sólo una parte. Como puede ser difícil conseguir una versión vieja, guarda las bibliotecas externas junto con tu código aunque necesites guardarla varias veces. Al precio de discos duros de hoy es más barato que pasarse un día buscando bibliotecas por ahí cuando toca un cambio en algunos años. Además, da mucha frustración deber entender un proyecto viejo y directamente no funciona o ni siquiera compila.
  • Crea una carpeta para la documentación editada y otra para la generada (por doxygen, javadoc o phpDocumentor. Ten en cuenta que la documentación generada puede crearse en varios formatos como HTML o LaTeX. Una forma de poner orden podría ser:
    • generated_doc –  La carpeta raíz de la documentación generada, contiene enlaces a la página principal index.html guardado en la carpeta “html”.
      • nombre_proyecto – El nombre del subproyecto
        • html – Un carpeta creada por la herramienta de documentación automatizada.

    De esta forma

    • Distinguimos fácilmente la documentación escrita (por un procesador de texto) de la generada.
    • Podemos, mediante enlaces a ficheros, acceder fácilmente a la documentación generada sin preocuparnos de cómo está guardada dentro de la carpeta “html”.
    • Será fácil limpiar una documentación vieja, ya que sólo necesitamos limpiar el contenido la carpeta nombre_proyecto.
  • Crea las carpetas (vacías) para los ficheros temporales que tus aplicaciones podrían generar. No guardes otra cosa ahí de forma que se pueda borrar todo su contenido sin borrar a nada importante.
  • Si una aplicación se comunica mediante ficheros, crea una carpeta entrada_mi_aplicación en que solo lee una aplicación. Así simplemente puede comprobar si hay fichero o no para procesarlo. La carpeta “salida” sería la “entrada” de otra aplicación.
  • Crea una carpeta para ficheros que sirven como base de datos, por ejemplo las imágenes subidas a un servidor web.
  • Puedes reunir las carpetas con datos temporales, de entrada y de base de datos en una carpeta de datos de aplicación. También puedes crear dentro la carpeta de cada tipo de información subcarpetas para cada aplicación.
  • Si usas una base de datos como MySQL, guarda backups en SQL junto con tu proyecto. Los ficheros que usa la base de datos en sí muchas veces no son tan fáciles a mover. Aparte de esto es probable que se comparte una base de datos entre varios proyecto y conviene no guardarla por debajo de una carpeta raíz del proyecto.
  • En tu proyecto puede tener también una carpeta para versiones viejas. Sin embargo, en este caso podría convenir crear una carpeta de proyecto nuevo.
  • Crea una carpeta para la configuración de la aplicación. Con esto nos referimos a ficheros que contienen el mismo tipo de datos, pero que se debe editar a mano para adaptarla a la plataforma o la máquina. Por ejemplo, el fichero “ip.ini” podría contener direcciones IP a usar por el programa. Es importante separar estos ficheros del programa porque la actualización del programa y la configuración de las máquinas en que corre son actividades independientes.

En fin hemos visto que son muchos los aspectos a tener en cuenta. Muchas veces es la experiencia que dice qué estructura es la que más conviene. Lo más práctico es copiar una carpeta cuando hace falta copiar algo y que esta carpeta ya contenga todo lo que será necesario. Cuando nos toca copiar varias carpetas en sitios diferentes, entonces sabemos que algo podemos hacer mejor.

Referencias

Anuncios

Escribe tu dirección de correo electrónico para suscribirte a este blog, y recibir notificaciones de nuevos mensajes por correo.

Únete a otros 52 seguidores

Archivos

febrero 2018
L M X J V S D
« Ene    
 1234
567891011
12131415161718
19202122232425
262728