JavaScript styleguide on organizing files

Question

I have worked in a web project with a heavy part on JavaScript, and I have noticed that there was no style how to use JavaScript. What unsettled me most is that everyone added files here and there, which resulted in a mess to organize and deliver them. Because this will be happen in every new project, I would like to have something like a styleguide for JavaScript. This styleguide should address the following questions:

• How should JavaScript files be organized in the file system during development?
• How should the JavaScript parts be separated from the HTML and other parts of the application?
• How should JavaScript files be delivered in the real application, so that less code has to be loaded on each request and not too much requests have to be sent?

Is there something public available as a starting point for developing our own styleguide? What are your experiences in using your styleguide? Are developers following it easily, what are the simple and what are the difficult parts in it?

(I know, more question than one, but I'm interested in the whole story here. As a background, we have used JQuery and JSF, but I don't think that will have an impact on the answer.)

Answer 1

If you're doing heavy client side, you are probably going the MVC way.

So I'll answer your questions with the approach taken by the brunch. Brunch projects use MVC library Backbone.js, and have strict directory structure.

How should JavaScript files be organized in the file system during development?

src/
  app/
    collections/
    controllers/
    models/
    styles/
    templates/
    views/
  vendor/
build/
  web/
config.yaml

Use Stitch to organize your files as CommonJS modules. Then you will be able to use require() to define dependency between them, as well as to combine them into one file later.

How should the JavaScript parts be separated from the HTML and other parts of the application?

build directory is used to store html; build/web is used to store javascript, images, and css.

How should JavaScript files be delivered in the real application, so that less code has to be loaded on each request and not too much requests have to be sent?

At the build stage, all JavaScript is minified and combined into one file (build/web/js/app.js), so that client will have to make only one HTTP request when he / she visits your site for the first time.

It's probably a good idea to make building process as easy as possible. Brunch does that by offering brunch watch command, which monitors filesystem for changes and builds code instantly with the help of Stitch and some other tools.

(It should be noted that during development brunch projects also use CoffeeScript as the primary language; it is transparently compiled by brunch before stitching the resulting JavaScript. However, this doesn't matter as long as file organization is concerned, and is out of scope of your question.)

Answer 2

For all JavaScript files definitely use a separate directory. Have as many files as possible semantically. One large constructor should correspond to a separate file. Never use filename prefixes where you can create a directory.

Unix-style directory structure is often found on GitHub:

• src -- for the source JavaScript.
• lib -- for libraries.
• tests -- for unit tests.
• bin -- for executables.
• dist -- for compiled files.

For compiling we use a Makefile with targets for production and development. The production version is all of files JSHint`ed, minified and concatenated into one. The development target is generating a server-side script that includes all JavaScript files dynamically (for easy inclusion into HTML).

But generally it depends. We used a widget directory for one project. This widget directory had a set of separate widget subdirectories (e.g. slider, tabs, modal-window), each of which had the following layout (inspired by DOMLoader):

• html -- for HTML templates.
• css -- for CSS files necessary for the widget.
• js -- for the widget JavaScript constructor.