My Node.js modules these days

example.js

// Short module explanation             // Something to gather my thoughts
//                                      // I think this looks cool.
                                        //
module.exports = the_exported_function  // Modules are a function. Always.
                                        //
module.exports.extra = extra            // Additional API entry points if
module.exports.other = other            // desired.
                                        //
var util = require('util')              // Other packages from npm or core
var assert = require('assert')          // No comma-first due to lots of
var whatever = require('whatever')      // churn in Git.
                                        //
var foo = require('./foo')              // Modules within this package
var bar = require('./bar')              //
                                        //
var ENABLE_BUGS = false                 // Globals in the module, upper-case
  , MODE = 'production'                 // I like comman-first. YMMV.
                                        // (Two blank lines)
                                        //
function the_exported_function() {      // The primary API entry point, either
}                                       // a function or constructor.
                                        //
function extra() {                      // Some other optional API function
}                                       //
                                        //
function other() {                      // Some other optional API function
}                                       //
                                        // (Two blank lines)
                                        //
function main() {                       // Optional main function for CLI
}                                       // execution.
                                        //
if(require.main === module)             // Run main() if this module is
  main()                                // executed rather than required.

Comments on the right-hand side are obviously not in the real code. That is the "directors commentary."

Each "directors commentary" comment refers to the actual code directly to the left, on the same line.

me likey

only thing I don't like is not having comma-first for require's

I do not like comma-first for requires either. It looks cool; but they change so often as the code evolves, it requires too much work to add and remove require() lines.

I still use comma-first for other variable initialization. However I don't really care much. Same for semicolons.

Why export anything "extra"? Could you give me an example?

@bhurlow in coux I have coux() be a GET ReST request, but you can run coux.put() coux.post() etc

@jhs Can you say a bit about why modules should always be functions? How might you structure, for instance, Underscore.js to work under that suggestion?

also, you can leverage that last line like this:

// IF RUN DIRECTLY via node <filename>.js
if(require.main === module) {
  // do stuff here 
}
// otherwise its a module
else {
  module.exports = the_exported_function
}

@jugglinmike underscore is a function. For example, you could do either _(arr).find(predicate) or _.find(arr, predicate) interchangeably

i sometimes come up with this pattern:

module.exports = function(confs, deps){
  var dep1 = deps.dep1 || require('dep1')
     , dep2 =  //and so on
  var conf1 = //same with confs
  return function theFunctionThatDoTheJob(/*args*/){ /*fancy code here*/}
}

//some static stuff here
var MYCONST = 'foo'
function fancyHelperStuff(){}

this way i'm ready for dependency injection. i don't do DI for all dependencies, but if i want to, i can. so i.e. the user can provide mikeals request as http client module or i just fall back to native one. same here for different EventEmitter implementations and so on.

@greelgorke Yes, for that I use my package, Defaultable: https://github.com/nodejitsu/defaultable