As JavaScript frameworks like jQuery make client side web applications richer and more functional, I've started to notice one problem...

How in the world do you keep this organized?

Put all your handlers in one spot and write functions for all the events?

Create function/classes to wrap all your functionality?

Write like crazy and just hope it works out for the best?

Give up and get a new career?

I mention jQuery, but it's really any JavaScript code in general. I'm finding that as lines upon lines begin to pile up, it gets harder to manage the script files or find what you are looking for. Quite possibly the biggest propblems I've found is there are so many ways to do the same thing, it's hard to know which one is the current commonly accepted best practice.

Are there any general recommendations on the best way to keep your .js files as nice and neat as the rest of your application? Or is this just a matter of IDE? Is there a better option out there?

EDIT

This question was intended to be more about code organization and not file organization. There has been some really good examples of merging files or splitting content around.

My question is: what is the current commonly accepted best practice way to organize your actual code? What is your way, or even a recommended way to interact with page elements and create reuseable code that doesn't conflict with each other?

Some people have listed namespaces which is a good idea. What are some other ways, more specifically dealing with elements on the page and keeping the code organized and neat?

Many good questions generate some degree of opinion based on expert experience, but answers to this question will tend to be almost entirely based on opinions, rather than facts, references, or specific expertise. If this question can be reworded to fit the rules in the help center, please edit the question.

I put different "namespaces" and sometimes individual classes in separate files. Usually I start with one file and as a class or namespace gets big enough to warrant it, I separate it out into its own file. Using a tool to combine all you files for production is an excellent idea as well.

Don't you need to export classes somehow? How does an object get created from the outside of such a module? Or should there be a method createNewSomething() in the return object, so object creation happens solely within the module? Hm... I would expect that classes (constructors) are visisble from the outside.
– robschJul 4 '16 at 7:35

I try to avoid including any javascript with the HTML. All the code is encapsulated into classes and each class is in its own file. For development, I have separate <script> tags to include each js file, but they get merged into a single larger package for production to reduce the overhead of the HTTP requests.

Typically, I'll have a single 'main' js file for each application. So, if I was writing a "survey" application, i would have a js file called "survey.js". This would contain the entry point into the jQuery code. I create jQuery references during instantiation and then pass them into my objects as parameters. This means that the javascript classes are 'pure' and don't contain any references to CSS ids or classnames.

I also find naming convention to be important for readability. For example: I prepend 'j' to all jQuery instances.

In the above example, there is a class called DimScreen. (Assume this dims the screen and pops up an alert box.) It needs a div element that it can enlarge to cover the screen, and then add an alert box, so I pass in a jQuery object. jQuery has a plug-in concept, but it seemed limiting (e.g. instances are not persistent and cannot be accessed) with no real upside. So the DimScreen class would be a standard javascript class that just happens to use jQuery.

I find that using $ as a variable name prefix is a more common practice, but I could be wrong. So, $s = $('...') instead of jS = $('...'), just a matter of preference I guess. Interesting though, since Hungarian notation is thought to be a code smell. It's weird how different some of my JavaScript code conventions/preferences are to my C#/Java coding conventions.
– jamiebarrowAug 25 '11 at 11:11

9

@jamie It isn't a code smell in this case, it's precisely one of the few cases where Hungarian is good. You might want to read this.
– Dan AbramovOct 2 '11 at 19:41

3

@DanAbramov thank you for the link. I really must read all of Joel's blogs, he explains things so well. Definitely deserves the fame/reputation he has. I will refer to Systems Hungarian as a code smell and Apps Hungarian as a practise from now on :)
– jamiebarrowOct 13 '11 at 10:20

I guess in the C# world, it also could be a great article to promote the use of var, now that I think about it. Most the arguments against using var is where you won't be sure of the 'type' of what is returned, but I guess the argument should rather be against not know the 'class' of what is returned. If using Apps Hungarian, you shouldn't have that concern then... interesting.
– jamiebarrowOct 13 '11 at 10:22

2

@Marnen: I see your point, but it isn't useless as a guide to the programmer. The $ prefix reminds me what it is when reading my code later, and thus helps quicker understanding.
– SeanJun 18 '13 at 20:28

Sometimes there are unneeded javascript scripts. It's wasteful to send those to the client. I think it's bes to only send what is needed. Of course, for a web app that's being used all day long, such as an intranet app, it might be better to send the whole batch at once, on the first page load.
– DOKOct 29 '08 at 17:52

There's also a concept of lazy loading to try and reduce bandwidth needs, where you load the initial page, and then perform asynchronous loading of the required script files (as mentioned in other answers to this question). Though, that may require more requests and actually could be less usable. @DOK, if the JS is cached, one medium request may be better than a few small ones.
– jamiebarrowAug 25 '11 at 11:20

Inspired by earlier posts I made a copy of Rakefile and vendor directories distributed with WysiHat (a RTE mentioned by changelog) and made a few modifications to include code-checking with JSLint and minification with YUI Compressor.

The idea is to use Sprockets (from WysiHat) to merge multiple JavaScripts into one file, check syntax of the merged file with JSLint and minify it with YUI Compressor before distribution.

If you done everything correctly, you should be able to use the following commands in your console:

rake merge -- to merge different JavaScript files into one

rake check -- to check the syntax of your code (this is the default task, so you can simply type rake)

rake minify -- to prepare minified version of your JS code

On source merging

Using Sprockets, the JavaScript pre-processor you can include (or require) other JavaScript files. Use the following syntax to include other scripts from the initial file (named "main.js", but you can change that in the Rakefile):

(function() {
//= require "subdir/jsfile.js"
//= require "anotherfile.js"
// some code that depends on included files
// note that all included files can be in the same private scope
})();

And then...

Take a look at Rakefile provided with WysiHat to set the automated unit testing up. Nice stuff :)

And now for the answer

This does not answer the original question very well. I know and I'm sorry about that, but I've posted it here because I hope it may be useful to someone else to organize their mess.

My approach to the problem is to do as much object-oriented modelling I can and separate implementations into different files. Then the handlers should be as short as possible. The example with List singleton is also nice one.

And namespaces... well they can be imitated by deeper object structure.

The idea is well used in other languages for GUI development. When something significant happens somewhere in your code you publish a global synthetic event which other methods in other objects may subscribe to.
This gives excellent separation of objects.

I think Dojo (and Prototype?) have a built in version of this technique.

Namespaces for Dojo code and custom code (dojo.declare()) — do not pollute the global space, coexist with other libraries, and user's non-Dojo-aware code.

Loading modules synchronously or asynchronously by name (dojo.require()).

Custom builds by analyzing module dependencies to create a single file or a group of interdependent files (so-called layers) to include only what your web application needs. Custom builds can include Dojo modules and customer-supplied modules as well.

Transparent CDN-based access to Dojo and user's code. Both AOL and Google carry Dojo in this fashion, but some customers do that for their custom web applications as well.

My boss still speaks of the times when they wrote modular code (C language), and complains about how crappy the code is nowadays! It is said that programmers can write assembly in any framework. There is always a strategy to overcome code organisation. The basic problem is with guys who treat java script as a toy and never try to learn it.

In my case, I write js files on a UI theme or application screen basis, with a proper init_screen(). Using proper id naming convention, I make sure that there are no name space conflicts at the root element level. In the unobstrusive window.load(), I tie the things up based on the top level id.

I strictly use java script closures and patterns to hide all private methods. After doing this, never faced a problem of conflicting properties/function definitions/variable definitions. However, when working with a team it is often difficult to enforce the same rigour.

I'm surprised no one mentioned MVC frameworks. I've been using Backbone.js to modularize and decouple my code, and it's been invaluable.

There are quite a few of these kinds of frameworks out there, and most of them are pretty tiny too. My personal opinion is that if you're going to be writing more than just a couple lines of jQuery for flashy UI stuff, or want a rich Ajax application, an MVC framework will make your life much easier.

"Write like crazy and just hope it works out for the best?", I've seen a project like this which was developed and maintained by just 2 developers, a huge application with lots of javascript code. On top of that there were different shortcuts for every possible jquery function you can think of. I suggested they organize the code as plugins, as that is the jquery equivalent of class, module, namespace... and the whole universe. But things got much worse, now they started writing plugins replacing every combination of 3 lines of code used in the project.
Personaly I think jQuery is the devil and it shouldn't be used on projects with lots of javascript because it encourages you to be lazy and not think of organizing code in any way. I'd rather read 100 lines of javascript than one line with 40 chained jQuery functions (I'm not kidding).
Contrary to popular belief it's very easy to organize javascript code in equivalents to namespaces and classes. That's what YUI and Dojo do. You can easily roll your own if you like. I find YUI's approach much better and efficient. But you usualy need a nice editor with support for snippets to compensate for YUI naming conventions if you want to write anything useful.

I'd agree with you about really long, chained commands, but one of the best parts of jQuery is that it keeps all Javascript out of HTML. You can setup event handlers for all your elements without "needing" to add IDs or on<whatever> events on your elements. As always, over use of any tool is bad...
– HugowareDec 23 '08 at 13:07

I've worked on huge, well-organized projects in jQuery. I don't know why you think it gets in the way of organization.
– Marnen Laibow-KoserAug 14 '11 at 3:41

I create singletons for every thing I really do not need to instantiate several times on screen, a classes for everything else. And all of them are put in the same namespace in the same file. Everything is commented, and designed with UML , state diagrams. The javascript code is clear of html so no inline javascript and I tend to use jquery to minimize cross browser issues.

good commenting is KEY - I'm glad you said it so I didn't have to. I would add consistent naming conventions, some sort of easily comprehensible organization strategy for variables &amp; functions, and as you mentioned, judicious use of classes versus singletons.
– matt lohkampNov 5 '08 at 12:53

Also, if you need UML and state diagrams, that probably means that your architecture is not clear enough from the code. Downvoting.
– Marnen Laibow-KoserFeb 15 '13 at 17:40

1

@Marnen Well-written projects include comments to describe WHY, not necessarily WHAT. The code already describes the WHAT, but often times you need something to describe WHY. Upvoting.
– CypherApr 7 '14 at 21:39

@Cypher Well-written projects have clear enough code that you can usually tell the "why", not just the "what". I wouldn't trust a comment to tell me the "why", because I have no guarantee that it's in sync with the code. Let the code document itself.
– Marnen Laibow-KoserMay 29 '14 at 15:16

In my last project -Viajeros.com- I've used a combination of several techniques. I wouldn't know how to organize a web app -- Viajeros is a social networking site for travellers with well-defined sections, so it's kind of easy to separate the code for each area.

I use namespace simulation and lazy loading of modules according to the site section. On each page load I declare a "vjr" object, and always load a set of common functions to it (vjr.base.js). Then each HTML page decides which modules need with a simple:

This strikes me as a little cargo-culty. jQuery.fn is a pointer to jQuery.prototype, because $() actually returns a new instance of the jQuery constructor function. Adding a 'plugin' to jQuery means simply extending its prototype. But what you are doing is not that, and there are cleaner ways of accomplishing the same thing.
– Adam LassekJan 27 '11 at 19:14

I believe he's simply creating static functions. I remember seeing it in jQuery's docs that this way of declaring static functions is acceptable
– Alex HeydMar 29 '11 at 20:30

Good principal of OO + MVC would definitely go a long way for managing a complex javascript app.

Basically I am organizing my app and javascript to the following familiar design (which exists all the way back from my desktop programming days to Web 2.0)

Description for the numeric values on the image:

Widgets representing the views of my application. This should be extensible and separated out neatly resulting good separation that MVC tries to achieve rather than turning my widget into a spaghetti code (equivalent in web app of putting a large block of Javascript directly in HTML). Each widget communicate via others by listening to the event generated by other widgets thus reducing the strong coupling between widgets that could lead to unmanageable code (remember the day of adding onclick everywhere pointing to a global functions in the script tag? Urgh...)

Object models representing the data that I want to populate in the widgets and passing back and forth to the server. By encapsulating the data to its model, the application becomes data format agnostics. For example: while Naturally in Javascript these object models are mostly serialized and deserialized into JSON, if somehow the server is using XML for communication, all I need to change is changing the serialization/deserialization layer and not necessarily needs to change all the widget classes.

Controller classes that manage the business logic and communication to the server + occasionally caching layer. This layer control the communication protocol to the server and put the necessary data into the object models

Classes are wrapped neatly in their corresponding namespaces. I am sure we all know how nasty global namespace could be in Javascript.

In the past, I would separate the files into its own js and use common practice to create OO principles in Javascript. The problem that I soon found that there are multiple ways to write JS OO and it's not necessarily that all team members have the same approach. As the team got larger (in my case more than 15 people), this gets complicated as there is no standard approach for Object Oriented Javascript. At the same time I don't want to write my own framework and repeat some of the work that I am sure smarter people than I have solved.

jQuery is incredibly nice as Javascript Framework and I love it, however as project gets bigger, I clearly need additional structure for my web app especially to facilitate standardize OO practice. For myself, after several experiments, I find that YUI3 Base and Widget (http://yuilibrary.com/yui/docs/widget/ and http://yuilibrary.com/yui/docs/base/index.html) infrastructure provides exactly what I need. Few reasons why I use them.

It provides Namespace support. A real need for OO and neat organization of your code

It support notion of classes and objects

It gives a standardize means to add instance variables to your class

It supports class extension neatly

It provides constructor and destructor

It provides render and event binding

It has base widget framework

Each widget now able to communicate to each other using standard event based model

Most importantly, it gives all the engineers an OO Standard for Javascript development

Contrary to many views, I don't necessarily have to choose between jQuery and YUI3. These two can peacefully co-exist. While YUI3 provides the necessary OO template for my complex web app, jQuery still provides my team with easy to use JS Abstraction that we all come to love and familiar with.

Using YUI3, I have managed to create MVC pattern by separating classes that extend the Base as the Model, classes that extends Widget as a View and off course you have Controller classes that are making necessary logic and server side calls.

Widget can communicate with each other using event based model and listening to the event and doing the necessary task based on predefined interface. Simply put, putting OO + MVC structure to JS is a joy for me.

Just a disclaimer, I don't work for Yahoo! and simply an architect that is trying to cope with the same issue that is posed by the original question. I think if anyone finds equivalent OO framework, this would work as well. Principally, this question applies to other technologies as well. Thank God for all the people who came up with OO Principles + MVC to make our programming days more manageable.

I use Dojo's package management (dojo.require and dojo.provide) and class system (dojo.declare which also allows for simple multiple inheritance) to modularize all of my classes/widgets into separate files. Not only dose this keep your code organized, but it also lets you do lazy/just in time loading of classes/widgets.

A few days ago, the guys at 37Signals released a RTE control, with a twist. They made a library that bundles javascript files using a sort of pre-processor commands.

I've been using it since to separate my JS files and then in the end merge them as one. That way I can separate concerns and, in the end, have only one file that goes through the pipe (gzipped, no less).

In your templates, check if you're in development mode, and include the separate files, and if in production, include the final one (which you'll have to "build" yourself).

Create fake classes, and make sure that anything that can be thrown into a separate function that makes sense is done so. Also make sure to comment a lot, and not to write spagghetti code, rather keeping it all in sections. For example, some nonsense code depicting my ideals. Obviously in real life I also write many libraries that basically encompass their functionality.

I'm starting to use it, even for very little / basic things, and it really helps in keeping the code clean and flexible. It's worth using even for simple client-side JS manipulations.
– ChetanMar 29 '11 at 2:46

I think this ties into, perhaps, DDD (Domain-Driven Design). The application I'm working on, although lacking a formal API, does give hints of such by way of the server-side code (class/file names, etc). Armed with that, I created a top-level object as a container for the entire problem domain; then, I added namespaces in where needed:

Nice for file organization. I do that with code. But in the end I compile my code in a... let's say dll. You need that with javascript too or you'll end up requesting 15 js files per page.
– grafficAug 23 '10 at 14:24

@MarnenLaibow-Koser The only issue with requesting 15 JS files on a page is how many HTTP requests the browser can handle at a time. So bundling them into one file allows the browser to be requesting other necessary files at the same time.
– iwasrobbedOct 11 '11 at 3:47

That's true, but after the first couple of hits, they'll be in the browser's cache, so they won't require HTTP connections.
– Marnen Laibow-KoserOct 11 '11 at 17:43

You can use jquery mx (used in javascriptMVC) which is a set of scripts that allows you to use models, views, and controllers. I've used it in a project and helped me create structured javascript, with minimal script sizes because of compression. This is a controller example:

Your question is one that plagued me late last year. The difference - handing the code off to new developers who had never heard of private and public methods. I had to build something simple.

The end result was a small (around 1KB) framework that translates object literals into jQuery. The syntax is visually easier to scan, and if your js grows really large you can write reusable queries to find things like selectors used, loaded files, dependent functions, etc.

Posting a small framework here is impractical, so I wrote a blog post with examples (My first. That was an adventure!). You're welcome to take a look.

For any others here with a few minutes to check it out, I'd greatly appreciate feedback!

FireFox recommended since it supports toSource() for the object query example.

I use a custom script inspired by Ben Nolan's behaviour (I can't find a current link to this anymore, sadly) to store most of my event handlers. These event handlers are triggered by the elements className or Id, for example.
Example:

You don't mention what your server-side language is. Or, more pertinently, what framework you are using -- if any -- on the server-side.

IME, I organise things on the server-side and let it all shake out onto the web page. The framework is given the task of organising not only JS that every page has to load, but also JS fragments that work with generated markup. Such fragments you don't usually want emitted more than once - which is why they are abstracted into the framework for that code to look after that problem. :-)

For end-pages that have to emit their own JS, I usually find that there is a logical structure in the generated markup. Such localised JS can often be assembled at the start and/or end of such a structure.

Note that none of this absolves you from writing efficient JavaScript! :-)