Why should I think about structure in my project?

This might seem like a stupid question, but I honestly don’t think people think about this enough. There are a number of reasons why project directory and file structure is vital to the long-term success of your project.

Inward and Outward

Firstly, proper structure will help you to better understand what you’ve done when you go back to fix a bug 6 months from now. Everything should make sense and be consistent or you will spend too much effort trying to track down why a bug exists instead of just fixing it and moving on. That is an “inward” benefit. It helps you.

Secondly, proper structure helps other developers understand what you have developed. This is helpful in the event you become a team lead and cannot spend time fixing bugs or adding features on that project yourself. In the event that you leave the company, it will also help the developers who are left to continue improving on the app. It will only make you look better and assist in not burning bridges. Karma always comes back… make it good karma.

Thinking Modularly

Another reason why structure is important is because it helps you think more clearly about the code you are writing. Keeping your code in fairly simple, small modules nested inside meaningful directories not only helps you write unit tests, it helps you to better understand the purpose of the bit you are working on. Keeping routes, controllers, authentication strategies, plugins, utilities, configurations, etc. in their own world will only help you (and the other developers on your team) in the end.

My Structure

Let me share with you the basic structure that I use on my projects. This is something that I have hammered out over the years that makes sense to me and the other members of my team. Feel free to leverage it for yourself and modify it to fit your needs.

|-- app

  |-- config
    |-- default
    |-- test
    |-- staging
    |__ production

  |-- controllers
    |__ my_specific_controller

  |-- models
    |-- model_1
    |__ model_2

  |-- plugins
    |-- my_plugin_1
    |__ my_plugin_2

  |-- routes
    |__ index

|-- gulp
  |-- tasks
    |-- task_1
    |__ task_2

|-- public
  |-- img
  |-- stylus
  |-- coffee
    |-- controllers
    |-- models
    |-- helpers
    |__ services
  |__ views

|-- test
  |-- controllers
  |-- plugins
  |__ models

app

The app directory contains all the code for the server. Anything that has to do with NodeJS goes in there.

gulp

This is my build folder. I prefer using gulp over yeoman or grunt, and I prefer to break my tasks out into their own modules instead of making one giant gulp file. Read about how I use gulp.

public

All UI components go into the public folder. My UI stack of choice is Jade, Stylus and CoffeeScript.

test

All my unit tests go in the “test” directory. I try to match the sub directories to their counterparts above them. So, for example, unit tests for controllers will go in the controllers sub directory.

Each project is a slight variation of the above structure. Depending on the needs of the project, there may be more or less directories in the tree. For example, I am working on an API right now in HapiJS (my NodeJS framework of choice)… and since there is no UI, I don’t need a “public” directory at all.

In later posts I will expand on the specifics of what happens inside each of these directories and which tools I use and how I use them (e.g. gulp, CoffeeScript, jade, stylus, etc.).