First, some JavaScript background.
Skip to the good stuff
Here at Imulus, we like to namespace our JavaScript by wrapping our classes in static modules. We accomplish this by simply creating an object literal with a variety of members: classes (constructors), constants, variables and static methods.
Here is a pared down example of a simple module:
var Application = { // the module, a static wrapper
FXSPEED : 500, // a constant (sort of)
user : { // a nested static object
id : 123
},
toggle : function(){ ... }, // a static method
Interface : function(){ // a class
this.initialize = function(){
this.active = true;
this.build();
return this;
}
this.build = function(){
...
}
this.doSomething = function(){
return "did something";
}
return this.initialize();
}
}
The benefits of this technique are obvious; it allows us to have loosely-coupled, modular code that is nicely organized, available without instantiation and protects the global namespace from pollution.
Application.active // true
Application.user.id // 123
var interface = new Application.Interface()
interface.doSomething() // 'did something'
In reality, however, one mammoth object literal in a single file is a lousy way to structure your code. Instead, what we do is organize module members into separate files in a logical fashion, å la Ruby. The module and all of its static members exist in a single file named after the module, and all of the module’s classes exist in a directory named after the module with each class file named after itself without the namespace. By using this structure, files are much easier to find because the naming convention mirrors the the module namespace.
The directory structure ends up looking like this:
|-- scripts
|-- application.js
|-- application
|-- controller.js
|-- data.js
|-- interface.js
And the module above would be structured like this:
// scripts/application.js
// creates the wrapper module and contains all static members
var Application = Application || {
FXSPEED : 500,
user : {
id : 123
},
toggle : function(){ ... },
}
// scripts/application/interface.js
Application.Interface = function(){
this.initialize = function(){
this.active = true;
this.build();
return this;
}
this.build = function(){
...
}
this.doSomething = function(){
return "did something";
}
return this.initialize();
}
// scripts/application/controller.js
Application.Controller = function(){
...
}
You get the picture. This probably looks familiar to a Rubyist. Here’s the analog:
|-- lib
|-- application.rb
|-- application
|-- interface.rb
# application.rb
module Application
FXSPEED : 500,
def self.user
{ 'id' => 123 }
end
def self.toggle
...
end
end
# application/interface.rb
module Application
class Interface
attr_accessor :active
def initialize
@active = true
build
end
def build
...
end
def do_something
'did something'
end
end
end
Snakes on a Train
By now it’s probably evident how much we obsess over code structure, organization and namespacing. While experimenting with CoffeeScript, this has been an ongoing concern.
This is the example from the CoffeeScript demo page:
class Animal
constructor: (@name) ->
move: (meters) ->
alert @name + " moved " + meters + "m."
class Snake extends Animal
move: ->
alert "Slithering..."
super 5
class Horse extends Animal
move: ->
alert "Galloping..."
super 45
sam = new Snake "Sammy the Python"
tom = new Horse "Tommy the Palomino"
sam.move()
tom.move()
I love that Coffee has made dealing with prototypes much easier with the ‘class’ and ‘extends’ keywords. This is great, and by itself works like a charm for singular, somewhat global classes. However, for any application with a sizeable codebase this simply isn’t practical without ending up with insane class names.
The ideal solution would be to introduce a ‘module’ keyword similar to Ruby’s.
module Zoo
class Animal
constructor: (@name) ->
move: (meters) ->
alert @name + " moved " + meters + "m."
bob = new Zoo::Animal "Bob the Bird"
bob.move()
Other people agree. But there are a number of JS limitations that prevent this from being a viable solution in CoffeeScript.
The Really Good Stuff
By its own golden rule, CoffeeScript is: “It’s just JavaScript”. So, we can namespace our CoffeeScript classes in the same manner we organize our modules in vanilla JS.
Extending on the example above (ha-ha, get it?), I’ll demonstrate how to namespace your Coffee classes in a simple, elegant way.
Focusing only on the snakes for now, lets set up our basic classes.
class Animal
constructor: (@name) ->
move: (meters) ->
console.log @name + " moved " + meters + "m."
class Snake extends Animal
move: ->
super 5
george = new Snake "George"
george.move() // George moved 5m
Now, we want to create ‘Forest’ and ‘Savanna’ modules that have a habitat and snakes of their own.

Just like JavaScript, we could wrap all of the module members in an object literal:
Forest =
habitat: "dense highland dotted with lakes and streams"
Snake: class extends Snake
move: ->
super 10
george = new Forest.Snake "George"
george.move() // George moved 5m.
But we would run into the same problem when the codebase reaches any kind of scale: enormous, single-file object literals. So let’s introduce a new function for creating module members.
module = (name) ->
global[name] = global[name] or {}
(Yes, I am aware that this is attaching the objects to the global namespace. This is what we want. It allows us to add members to the module later.)
Now we can use the ‘module’ function like this:
module 'Forest'
Forest.habitat = "dense highland dotted with lakes and streams"
Forest.Snake = class extends Snake
move: ->
super 10
george = new Forest.Snake "George"
george.move() // George moved 10m.
Pretty elegant, right? Additionally, by using the ‘module’ function we can now organize our code into multiple files:
module = (name) ->
global[name] = global[name] or {}
# src/animals.coffee
class Animal
constructor: (@name) ->
move: (meters) ->
console.log @name + " moved " + meters + "m."
class Snake extends Animal
move: (meters) ->
super meters
# src/forest/snake.coffee
module 'Forest'
Forest.habitat = "dense highland dotted with lakes and streams"
Forest.Snake = class extends Snake
move: (meters)->
@distance = meters || 5
super @distance
# src/savanna/snake.coffee
module 'Savanna'
Savanna.habitat = "grassy woodland small or widely spaced trees"
Savanna.Snake = class extends Snake
move: (meters)->
@distance = meters || 10
super @distance
george = new Forest.Snake "George"
george.move() // George moved 5m
scott = new Savanna.Snake "Scott"
scott.move() // Scott moved 10m
We can also extend standalone classes with module classes:
class Python extends Savanna.Snake
constructor: ->
super
console.log "I am #{@name} the python."
console.log "I live in the savanna,
where it is #{Savanna.habitat}."
class Cobra extends Forest.Snake
constructor: ->
super
console.log "I am #{@name} the cobra."
console.log "I live in the Forest,
where it is #{Forest.habitat}."
john = new Python "John"
// I am John the python.
// I live in the savanna,
// where it is grassy woodland small or widely spaced trees.
bruce = new Cobra "Bruce"
// I am Bruce the cobra.
// I live in the forest,
// where it is dense highland dotted with lakes and streams.