Recommended practices for JavaScript library formatting prior to publishing

Question

Say you have just implemented a JavaScript library that contains a few functions, ex:

double = function(a){ return a*2; };
root = function(a,b,c){ return -b+Math.sqrt(b*b-4*a*c)/(2*a); };
hypotenuse = function(a,b){ return Math.sqrt(a*a+b*b); };

It's not a good idea to distribute it like that because that code pollutes the global namespace.

What's a proper way to format a JavaScript library prior to publishing?

I'd recommend you to simply have a look at existing popular js projects on github and make your mind about what you prefer. — Denys Séguret, Jan 21 '13 at 19:54
The jQuery way? see this http://stackoverflow.com/questions/4556110/creating-a-jquery-like-object — Alexandru Calin, Jan 21 '13 at 19:54
You could look for the module pattern, but there are really many different patterns and not one that you should choose. — Denys Séguret, Jan 21 '13 at 19:55
The problem is that big libraries are big, so it's hard to isolate what I'm asking for, and small libraries could be using bad pratices I'd better not to copy. SO could put a word of authority providing a good pratice for me and anyone else looking for the same answer. — MaiaVictor, Jan 21 '13 at 19:56
I think putting them in an `object` makes more sense as these seem to be static methods. They could be put into one `object` that pollutes the global space. And even then, you can break down that main `object`. If you needed a "class", you'd probably use the `function` way. — Ian, Jan 21 '13 at 19:56
There may not be a top result from SO, but if you just Google "javascript classes", you'd find some distinction between using `object` and `function`. — Ian, Jan 21 '13 at 20:06

Denys Séguret · Accepted Answer · 2013-01-21T20:26:30.303

As your functions don't use classes, don't need a state, and are related to a simple topic, you could simply publish them as

myMath = {
   double: function(a){ return a*2; },
   root: function(a,b,c){ return -b+Math.sqrt(b*b-4*a*c)/(2*a); },
   hypotenuse: function(a,b){ return Math.sqrt(a*a+b*b); }
};

Now suppose you'd want to use a private function or a state, then you could use the module pattern :

myMath = (function(){
   var square = function(x){return x*x}; // private function
   return {
       double: function(a){ return a*2; },
       root: function(a,b,c){ return -b+Math.sqrt(square(b)-4*a*c)/(2*a); },
       hypotenuse: function(a,b){ return Math.sqrt(square(a)+square(b)); }
   }
})();

But there really is no reason here to use this construct.

Now note that publishing on github is much more than that (documentation, test units, readme.md, etc.) but that hardly can be discussed constructively on SO.

Simple and efficient, couldn't be better. Thanks. – MaiaVictor Jan 21 '13 at 20:05 — MaiaVictor, Jan 21 '13 at 20:05

score 2 · Answer 2 · edited May 23 '17 at 10:24

The discussion about how to properly namespace your Javascript functions is pretty well documented (See #2 below). I'll focus on the things that are often forgotten when publishing libraries:

Documentation. I can't stress this enough. Anyone who wants to use your library needs to know what it does and some examples of how to use it. People often breeze through documentation, but they will focus on examples so make sure those examples teach them the preferred ways to use your library. Providing documentation both inside and outside of your source is extremely helpful in gaining adoption.
Namespace your functions so that you play well with others. See How do I declare a namespace in JavaScript? for how to accomplish this in Javascript.
Use variable, parameter and function names that describe their uses. A variable name of b often tells the user nothing about its intended use. It's ok if they are long, that's why we provide a minified version for production use.
Make your library easy to consume. Provide a simple download and instructions for how to get started with it.
Communicate with your users. If your project is open source, make it easy for people to communicate the difficulties they are having with it (Bug tracking, GitHub issues, mailing list, etc.). This will help build a community and perhaps even get people interested in contributing back.

There are definitely additional ways to improve your published library, but these things are common to the most popular libraries out there, so you might consider them before trying to spread the word on your library. Good luck!

Those are really great advices, I have a better idea of how to do it now. I'm publishing my first library today (that's 2 very simple functions, actually) - but I'll be glad just to know I'm contributing to the programming community the way I can. — MaiaVictor, Jan 21 '13 at 20:22

Recommended practices for JavaScript library formatting prior to publishing

2 Answers2