I’m working on small JavaScript library for cross-(sub)domain communication through iframes for users of our platform and my target audience will have little to no JavaScript experience. While I’m going to have extensive documentation, my goal really is to make this library like HTML – easy to understand and pickup, without necessary having to consult a reference. Generally, I want one site creator (we call them affiliates) to look at another person’s site, say “How did he do that?”, view the source code, copy it, and implement it on her own site by altering the code.

My initial setup code (to configure/initialize) the library looked like this:

document.domain='mydomain.com';
Library.init('sub.domain.com',5166);

After looking back at it I thought about converting it to this:

document.domain='mydomain.com';
Library.setCommunity('sub.domain.com');
Library.setAffiliateSiteId(5166);
Library.init();

This is really clean and easy to understand but a little much if I need to add a ton more settings in the future.
My latest iteration looks like this:

document.domain='mydomain.com';
Library.configure({community:'sub.domain.com', affiliateSiteId: 5166, showErrors: true});

Although passing (JSON) objects around isn’t the most easy to understand for people with little or no JavaScript knowledge, it isn’t that unreadable and I really feel the pros outweighed the cons. In some of my methods there will be so many arguments that passing an object would be necessary and the user implementing the library is going to have to learn the syntax regardless. Plus passing data in a regular argument (x,y,z) format isn’t really good for optional parameters of which they’ll be a ton of in this library.
I’ve also decided to remove the initialize method and just auto-initialize once you’ve configured your settings. The more I can take away from the process the better.

Lastly, I added an optional error mode that will trigger an alert if you’re doing something wrong. The idea would be to disable it (remove or set  it to false) when you’re ready for production. This may add substantial bloat to the codebase so it may not stay in – or I could keep this feature in the dev version of the code and recommend affiliates use the production version after the initial creation process.

Note: The library isn’t actually called “Library”. I’m hiding it’s name until it’s ready. ;)