I tend to think this is the most suited solution in terms of maintenance, readability and scalability for my needs. You are welcome to share your personnal experience by dropping a comment.
It is really important to have automation even in your dev environment, otherwise you could end up with different configuration between your CI environment and your dev workstation. So please, use the exact setup in both otherwise I would give you this:
Picture taken from codinghorror
I personally use Grunt to automate my "build", tests, minifications,... tasks.
Autome your coding style
It is important that any developer in your team use the same formating syntax, it helps readability and maintainability. To avoid this task to become a burden we have enforce it with jsHint and the JsFormat plugin for sublime. When saving the file, it automatically formats the style using our configuration and when "building" the file, jsHint would make sure that the code meets the quality level we have decided. About coding style, I personnaly like idiomatic.js.
Split your code into mutiple files/modules
By using commonJS style, it is also very easy for me to spread code into different files and having a structure which make sense. A model folder for my object, a controller folder, a helper folder... At the end all those files are put together with the help of the index.js file (called the main file in npm).
Isolate the DOM
I always try to keep all DOM related tasks in their own files or even module(s) even if I use something like Zepto or jQuery. Multiple reason for that:
By knowing which part of the code is relying on the DOM, you could extract the rest in another module. As this module won't have any DOM related work, you could easily use it inside a node.js environment.
Build your file
As you know, if you attach a commonJS file in your browser, that won't work very well. In order to make it, I am using a tool called Browserify. It will generate for me a file that can be used by the browser without changing my codes.
At the end, you will end-up with a framework which would enforce code re-use and consitency for your development team.
I always gateher my ajax calls and create Repositories to pull the data. This repository could point to a local storage or to some HTTP endpoints, at the end it won't really matter.
When I am not using a library like Backbone, Angular,... I try to stay away from the jQuery ajax and prefer to use something like superagent. As you would notice, I do not like big libraries which does everything, I prefer to use granular libraries which focus on solving only "one problem" at the time. Superagent also has the advantage to have the exact same API in node.js.
Testing your module
Divide your tests in 2 parts
- The ones that can be run in node.js.
Why would you need to have a browser open if you don't need it.
- The ones that need a browser
Obviously, if you write a module for the browser, you will need it at some point.
Open a browser only if you need it
For the browser tests, I use phantomJS in order to prevent me opening a browser each time I need to execute my tests. If you use mocha and grunt (like me), you could even use the mocha-phantomJS to automate the execution.
Let X-Browser tests to your CI
I rarely execute my browser tests using a specific browser. I let the CI doing this. Generally, I would have a selenium task defined which will open each "runner" I have for my browser tests and let selnium doing the testing for me. I would open my browser only in case of problems reported by the CI.
Tests well written are generally the best source of documention. A nice README.MD is also a good start. If you have none of both, I would start with that.
I only put docBlockR comments on the public method. When I want to mark the developer attention about a comment, I just use an inline comment. Having fewer comments accross the code, let the developer focus on the comments which really matter.
In order to express everything explained in that blog post, I have created a repo that is "ready" to welcome your code.