So far we’ve made some pretty important decisions regarding the technical stack and tools to be used while constructing the sample SCRUM application. Now, we need to answer one more crucial question; how to organize different files in a meaningful folders structure.
There are multiple ways of organizing files in any given project. Sometimes choices are made for us since some of the existing tools and frameworks force a prescribed layout. But neither grunt.js nor AngularJS imposes any particular directory structure so we are free to make our choices. In the following paragraphs, you can find one proposal for organizing files and the rationales behind this proposal. You might choose to use the described structure as is in your future projects or tweak it to suit your particular needs.
Root folders
While designing folders layout we would like to end up with a directory structure that makes it easy to navigate in the codebase. At the same time, we need to keep build complexity at a reasonable level.
Here are some basic assumptions leading us to the high-level directory structure:
- The source code for the application and the accompanying tests should be clearly separated. This is to keep the build system easy to maintain, as there are usually different sets of build tasks to be executed for tests and for the source code.
- Third-party code for any external libraries should be clearly isolated from our internal codebase. External libraries will be changing at a different pace as compared to our deliverables. We want to make it easy to upgrade external dependencies at any time. Mixing our sources with external libraries would make such upgrades harder and time-consuming.
- Build-related scripts should reside in their own dedicated folders and not be scattered through the codebase.
- Build results should be outputted to a separate folder. The content and structure of the build output should closely match the one mandated by the production deployment requirements. It should be very easy to just grab the output of the build and deploy it in its final destination
Taking all of the above assumptions into consideration we ended up with the
following set of top-level directories in the project:
- src: It contains the application’s source code
- test: It contains accompanying automated tests
- vendor: It contains third party dependencies
- build: It contains build scripts
- dist: It contains build results, ready to be deployed in a target environment
Inside the source folder
The index.html file is the entry point to the sample application. Then, there are four folders, two of them holding AngularJS-specific code (app and common) and two others contain AngularJS-agnostic presentation artifacts (assets and less).
It is easy to decipher the purpose of the assets and the fewer folders; the first one holds images and icons while the second one, fewer variables. Please note that the fewer templates for Twitter’s Bootstrap CSS are located in the vendor folder, here we just keep variable values.
AngularJS specific files
AngularJS applications consist of two different file types, namely, scripts and HTML templates. Any non-trivial project will produce many files of each type and we need to find a way to organize this mass of files.
Ideally, we would like to group related files together and keep the unrelated ones further apart. The trouble is that files can relate to each other in many different ways and we’ve got only one directory tree to express those relations.
