I wrote this about six months ago before starting work on base2. I decided not to post it at the time as I thought it sounded a little pompous. On reflection, they aren’t bad rules and I managed to stick to them. So, here the rules I wrote for myself back in October.
- 1. Be unobtrusive
- My HTML doesn’t want to know about your JavaScript.
- 2. Object.prototype is verboten!
- This is so important that it needs a rule all to itself. Objects are the basic building blocks of JavaScript functionality. Don’t mess with them.
- 3. Do Not Over-extend
- The less you extend JavaScript’s built-in objects the better. Don’t get me wrong. Native JavaScript objects are a little sparse on useful methods. You will feel obliged to add one or two of your own. But “one or two” is not enough for the creative (library) programmer. Stop! Just add what you need. The less you extend JavaScript’s built-in objects the less you will clash with other libraries.
- 4. Follow Standards
- As a library writer you are defining patterns of JavaScript code. Patterns are signs of weakness in programming languages. Remember, JavaScript and the DOM are continually being specified. If you are going to “fix” something then look to see if it has not already been fixed. Consider available solutions. If you follow standards, then follow them closely (e.g. don’t skip a parameter on a
forEachmethod). - 5. Or Follow The Leader
- Mozilla leads the way in JavaScript. The creator of the language, Brendan Eich, continues to develop it. New language features are available in Mozilla browsers before any other. If you are going to add language features to JavaScript then look to Mozilla standards first. For example, if you want to extend
Arrayto allow an enumeration method, then call that methodforEachinstead ofeach. If you do provide missing language features then follow existing standards closely (see above). - 6. Be Flexible
- What if I want to modify behaviour without changing the source code of your library? How easy is that? Not easy enough. Make it easier.
- 7. Manage Memory
- People care about memory leaks. Do your job.
- 8. Eliminate Browser Sniffing
- It seems that browser vendors will forever compete by adding new features.
As a library author you must keep up with the latest fashions. It is not good enough to browse Ajaxian occasionally. You must slavishly read every blog to find the next hack. Browser sniffing can be addictive. - 9. Small is Better
- JavaScript libraries have come of age. Some of them now power premier sites. But we are not all on 2MBit DSL lines. So keep your library small. Better yet, provide a build page that allows me to efficiently build my library according to my needs.
- 10. The Tenth Rule
- Good ol’ tenth rule. You can always rely on the tenth rule. The tenth rule is: be predictable. I should be able to guess what your methods do. And if I don’t know what a method is called then I should be able to guess that too.
- 11. Bonus Rules
-
- Documentation. Annoying but true.
- The more namespacing you use, the less likely I am to remember your phone number.
- Remember that potentially millions of people will be executing your code.
For the record, base2 does not alter any native JavaScript objects.
Comment: #1.
Dean, one src (about 6 Kb on Gz compatible browsers), JS 1.5 Standard for every browser, without Object prototypes and with every prototype implemented as standard (and few extra features not prototyped too).
This is to tell that You released a library (Base2) that’s not so different from my old JSL concept (and goal) and my new FW … but You was faster than me to release “officially” this cool library.
What do You think about merging our code for a better standard “BaseFX” library development?
I can send You my debugged sources (point 4 and 5 of this post) to implement correctly even XMLHttpRequest for IE 5 or greater (as new perfect String.replace and every other Native methods)
Regards
Comment: #2.
I agree with most but life is tough in JavaScript land…
1) Being unobtrusive is not easy http://peter.michaux.ca/article/553
3) Don’t extend built in objects at all. Then you don’t have to worry about clashes. I don’t see much difference in writing forEach(myArray, function(a){return a;}) then myArray.forEach(function(a){return a;});
“You must slavishly read every blog to find the next hack”
I don’t think any code in a library should be a “hack”.
9) The Base OOP code seems quite long. JavaScript OOP with “super” in eight lines: http://www.kevlindev.com/tutorials/javascript/inheritance/index.htm
11.1) Writing documentation is a valuable way to look at library code though a different set of glasses. It really helps my development process.
11.2) Namespacing allows people to use a library in a legacy environment. Those who don’t want to type the namespaces can import the namespaced properties into the window object. Without namespaces you are leaving out the legacy developers.
Just some thoughts. The more JavaScript libraries the better since there is more ideas and analysis of browser scripting difficulties. It is unfortunate that we all have such different sets of priorities and can’t just have one library.
Comment: #3.
Yes it is. But I’m happy with it. I don’t really like the other solutions available.
It is a JavaScript library.
My intent is that you should eliminate sniffing for the user of the library.
That was a joke.
Comment: #4.
Comment: #5.
Then, if you’re a fan of jQuery, why don’t you introduce your library to the jQuery developers so as to drop all of their sniffing and depend on base2? That way we could use jQuery and base2 together without problems I guess.
Comment: #6.
@knocte - if you like jQuery already then I really recommend that you continue to use it. base2 offers nothing more than jQuery already provides. Byte for byte, jQuery provides a lot more power.
This library is not really meant to compete with jQuery or Prototype. Those libraries already provide lots of functionality that base2 does not.
base2.DOM is really aimed at:
Comment: #7.
Comment: #8.
Thank You Dean to ignore me totally, regards.
Comment: #9.
Indeed you are right on with all these, but this also leads me to believe that no library is doing all these things. With my recent release of D|C I went through the annoying hassle of writing documentation. I suppose some documentation is better than none, no matter how long your phone number is
Predictability is also key since there’s nothing worse than thinking something is something that it isn’t. That is one main reason I allowed the ability to change D|C through registration.
Another thing… man I’m really glad you posted this… because D|C has a simple plugin method which allows you to extend the library without touching the source… one thing I knew I needed to have. And lastly your first rule. Always a given. That was my big argument over the “just add a classname widget philosophy.” Das no good.
Comment: #10.
About point 4 (Follow Standards)
Both your Function.apply and Number.toFixed don’t respect standards.
function bug(){return [].slice.apply(arguments)}; alert(bug(1,(2).toFixed(2),3));apply accepts one *optional* argument (as call) and (2).toFixed(2) should return string “2.00″ . As I said, bytefw has just solved these common problems … and, for example, the fastest version of unshift should be something like this
[].unshift = function(){ this.reverse(); while(arguments.length) this[this.length] = arguments[--arguments.length]; return this.reverse().length };This post just to tell You that a collaboration should be better without wasted time and with less bugs because, as You said:
look to see if it has not already been fixed
and for example, again, your encodeURIComponent implementation is not standard too while mine one is (and unescape as decodeURIComponent is a bad practice, imho).
bye
Comment: #11.
@Andrea - what’s wrong with my version of
encodeURIComponent()? And, can you keep questions about base2 on the base2 page please?Comment: #12.
Dean: how would you propose to implend for instance toJSONString() without prototyping Object?
Comment: #13.
Comment: #14.
@Dean, about your encodeURIComponent [tested with FireFox]
example
Sure but these are errors about fourth point of this list (these functions don’t respect standard and don’t follow the Leader too)
Regards
Comment: #15.
@Tino Zijdel - you don’t have to extend the Object.prototype to make json work. Prototype (http://www.prototypejs.org/, rev 1.5.1rc2) has json support built in and they extend the Object singleton (not the prototype). var foo = Object.evalJSON( myJSONString );
@Dean - I dig your article. Great points. I like the idea of a build page to let me choose what components I want to add. As libraries get bigger, and they do overtime, its nice to just pick out what you need. For example, the Prototype SVN repo has all the main parts like (ajax,string,number,event,core) sep. into their own files, but no official build page 8(.
@Andrea Giammarchi - this is a post over Dean’s work, not a place to promote your framework. I like your blog posts too, but try to keep them separate. Your comments on the bugs though, are great. Frameworks should be beaten on by users. Many times I miss little errors in my projects becuase I am too close to them. An outside eye can really help.
Comment: #16.
j: what I was actually aiming at is that toJSONString() and parseJSON() are expected to be added in ECMA4. If you like to take the standards approach - as Dean is doing here with Base - that means that in order to have these (near) standard methods available in older (now current) browsers you probably need to prototype Object.
Another example: how would you ‘backport’ for instance the hasOwnProperty() method to IE5?
Comment: #17.
@Tino - well some things are impossible.
Comment: #18.
“9. Small is Better”
You hit one of the points why I wrote jsPax. A growing part of my js-code uses jQery and various plugins. I had the options of
With jsPax I usually have two script tags on a Page and still make perfect use of the browser cache. BTW I can dynamically change the set of loaded libraries according to the content of the page. That way I don’t have to care if I change the HTML if the according script will be loaded.
Comment: #19.
Comment: #20.
Although base is a different library as jQuery and has a different target audience, I still think that there should be more collaboration between you so as to give a really nice JS framework, avoid code duplication, etc.
Comment: #21.
I think you should add another two rules:
1 - test your code (Mochikit seems pretty keen on this point)
2 - benchmark your code - speed optimization, stress testing, etc… I think the whole discussion about memory leaks apply here too.
On rules #4 and #5: I must be the only person in the world who thinks forEach loops are bad =(
Comment: #22.
Comment: #23.
Comment: #24.
Comment: #25.
Dean,this is a very nice set of rules, and it is not pompous at all. I would do great work if I was able to stick to just some of them, as I always have some memory leaks and over-extending is my specialty. Thanks for the post, now I can see how many things I was doing wrong.
Comment: #26.
“base2.DOM is really aimed at:
teachers and students who are learning JavaScript and the DOM programmers, who are already familiar with JavaScript but don’t want to learn a new API web standards zealots”
Dean Your right im one of the students
And i fully agree with that what You say.
Comment: #27.
These are some great rules. I totally agree with you on number 6 - Be Flexible, in my opinion it should be the most important rule and much more programmers should stick closely to it, including me. It happened more than few times to me when I had to rewrite most of my code just to change one little behavior thing and that can be really frustrating. So flexibility is a great thing if it can be achieved.
Comment: #28.
Are there any documents out there explaining a good way to lazy-load classes and utilities as needed?
I am concerned with the size of my current js library (one file) growing with functions that are not necessarily needed on every single page that the library is included on.
Comment: #29.
Flexibility is a key to success. I would make “Be Flexible” rule #1 in this list.
Good luck with base2 Dean.
Regards, Marcus
Comment: #30.
I would reccomend that people who right JS libraries create different extensions, rather than stuff everything in one file, have the ability to extend it so you only have what you need, it is no good having some fuctions that will be rarely used in a website adding to the size of the file. Have the ability to easy extend the library with files, as and when you need them.
I think this goes with rule 9 you mentioned, this will keep your code small, but still have the functionality to add different functions that you need I think that is a must have.
Do you know of the best way to allow extension inclusion? As in ways to load the extension files into the main core file.
Thanks for the guide Dean!
Comment: #31.
Nice, the tenth rule seems my favorite
Comment: #32.
Hi Dean, quite a nice collection of rules you have placed here. But don’t you think that in reality one is actually never able of keeping all rules at once? In my opinion everybody has to fix priorities and must find out which of the rules is the most important one for himself. Rule Nr. 9 is very important for me. It’s difficult to understand why there are so many programmers who write that extremely exaggerated code. There still exists a large of number of peoples who is only provided with a bad connection to the Internet and DSL is not yet very widespread.
Comment: #33.
2. Object.prototype is verboten! =========================
I don´t know much about programming, nevertheless I sometimes stroll over pages like this, to get an impression and ideas.(even without going deep into it, there are sometimes chances, and - what a luck - I have a programmer for such things. But without understand a lot, I was smiling about using the german term “verboten” in relation to a seemingly strict “order” or recommendation about using a coding
Please believe me: not everything in Germany is “verboten” 
But if something is “verboten” - obey! (ok, that´s a little offtopic, just smile, as I did!)
regards from sunny Munich, Germany
Hans
Comment: #34.
Ha ha, I also studied German language in high school and I know that verboten is a really strong word! Dean, cool rules collection, luckily not all of them are “verboten” so they can be bent a little, but if they were only a little bit respected they can be really helpful.
Comment: #35.
I love tenth rule
- but thank you for whole list
Greg
Comment: #36.
Yar!
Comment: #37.
Hi Dean, Thx for providing us rules for JavaScript library authors. Indeed you are right on with all these. Make it small, flexible and standards-based:) looks great to me.
Comment: #38.
Comment: #39.
These rules are really good, if everyone follow these rules the code will be much better to support and to insert little changes…
Comment: #40.
Comment: #41.
Comment: #42.
Comment: #43.
Comment: #44.
Comment: #45.
Comment: #46.
Comment: #47.
Comment: #48.
Comment: #49.
Comment: #50.
Comment: #51.
Comment: #52.
Comment: #53.
Comment: #54.
Comment: #55.
Comment: #56.
Comment: #57.