In all the ways I've worked with Javascript, I find that nothing ever satisfies my desire for self-documenting code. I want to be able to see the APIs of modules, functions, "struct" fields, and event payloads within my own code.
I'm curious if any IDEs or transpiled languages help people easily keep their internal API visible? For example, with many languages, often an IDE will give an expandable tree view of packages/modules/classes/functions. Javascript makes this difficult as there are so many ways to code all of these entities.
I find when writing an application in Javascript that after it reaches a certain size, I have to keep jumping between source files to remember these things. Consistent naming, clear coding style, and such good habits only go so far. In a language that has no static typing, very loose rules around function arguments, and passing functions as callbacks, JS code can be hard to scan and immediately see the higher-level structure. It's hard to separate interface from implementation, as all JS code is implementation.
In large projects with many programmers, it makes sense to enforce rules about documenting functions in comments and maybe auto-generate docs. But doing independent development, this is like a lot of manual work just to remind oneself of the architecture and internal API, and likely to be out of date most of the time. I'm not going to look up a function to remember what params it takes, see that it has no docstring comments, add them and rebuild the docs so I can go read them.
TypeScript sounds promising but seems too tied to Microsoft tools. CoffeeScript saves typing and can make for cleaner code, but I don't think it solves the problem of exposing a high-level view of the structure of an application.
WebStorm actually exposes some of what I'm looking for, but I wonder what else exists.
I'm looking for any tips, tools, techniques others use to mitigate this issue.
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 9 years ago.
Improve this question
I want to create a custom UI framework in JavaScript for web applications (like Google Docs ui) (do not confuse with web application that deploy using languages like PHP, Python, etc.). However, after reading several books about web development, I understand that the best website is layered as follows:
Structure in HTML
Presentation in CSS
Behaviour in JavaScript
So there are several approaches to creating my own HTML document and control it in JavaScript. However in this approach HTML and CSS will be mixed, like in case of extJS UI. I am confused now, and I need some answers from experienced developers on how to write this kind of framework.
If HTML, CSS, and JavaScript is mixed.
What was advantages?
What was disadvantages?
Is there are other methods?
What was the usual type of creating UI frameworks?
I apologize that this answer is extremely long and at times may seem somewhat off-topic, but please keep in mind that the question was not very specific. If it is improved, or made less general, then I will gladly remove the superfluous parts, but until then, just bear with me. This is somewhat of a compilation of the other answers here, in addition to my own thoughts and research. Hopefully my ramblings will be at least somewhat helpful for answering this question.
General Tips for Frameworks
Frameworks are a ton of work, so don't spend all of that time for nothing. Work Smarter, Not Harder. In general, you should remember these things when creating a framework:
Don't Reinvent the wheel: There are tons of great frameworks out there, and if you create a framework that does the exact same thing as another framework, you've wasted a ton of your time. Of course, understanding what goes on inside another library is a great way to make your own library better. Quoting #ShadowScripter, "knowledge -> innovation." However, don't try to rewrite jQuery by yourself. :)
Solve a Problem: All good frameworks (and programs) start with a problem they are trying to solve, then design an elegant solution to solve this problem. So don't just start writing code to "create a custom UI framework," but rather come up with a specific problem you want to solve, or something you want to make easier. jQuery makes selecting and manipulating the DOM easier. Modernizr helps developers identify the features supported by a browser. Knowing the purpose of your framework will make it more worthwhile, and may even give it a chance of becoming popular.
Fork, don't rewrite: If the problem you aim to solve is already partially solved by another framework, then fork that framework and modify it to fully fit your needs. There's no shame in building of the work of others.
Optimize and Test: This is kind of a no-brainer, but before publishing version 1.0 on your website, test every single part of the function, under every single possible scenario, to make sure it won't crash and burn in production. Also, another no-brainer, minify your code (after testing) for performance benefits.
DRY and KISS: Don't repeat yourself, and keep it simple, stupid. Pretty self-explanatory.
Stick to Stable: (This is mostly my personal opinion) Unless you're trying to create a framework specifically targetted to HTML5 in Chrome 31, using experimental features and unstable code will make your framework slower, uncompatible with older browsers, and harder to develop with.
Open Source: (Another of my opinions) It takes years for huge companies like Google with thousands of dollars invested to create frameworks (e.g. AngularJS) so it is an excellent idea to make your source openly available. Having a community of developers contributing to your project will make development faster, and will make the end product faster, bug-free, and better all around. Of course, if you're going to sell it, that's another story...
For more information about best practices when making libraries, take a look at these links:
Javascript Library Design
Javascript Module Pattern: In Depth
Best Practices in Javascript Library Design
Building a Javascript Library
Types of Frameworks
The first thing you need to think about, as mentioned above, is what functionality you want your framework to provide. Here are is the list of types of frameworks/libraries (thanks to #prong for the link). For a much more comprehensive list, see jster, which has 1478 libraries, put into 8 categories, each with several subcategories.
DOM (manipulation) related
GUI-related (Widget libraries)
Graphical/Visualization (Canvas or SVG related)
Web-application related (MVC, MVVM, or otherwise)
Pure Javascript/AJAX
Template Systems
Unit Testing
Other
As you can see from the link, there are already dozens of libraries and frameworks in each of these categories, so there's not exactly much room for something new. That being said, I don't want to discourage you- who knows, you could create the next bootstrap or jQuery. So, here are some resources about each type of framework.
Note: you can't say that any type is better than the others, they simply are designed for different goals. It's like comparing apples and oranges.
DOM (manipulation) related
These types of libraries are designed to interact with, modify, and control the DOM of a website. Here are just a few of the things they do:
Select Elements in the DOM ($("div#id .class"))
Add/Remove Elements in the DOM ($("div#id .class").remove())
Edit Attributes of Elements in the DOM ($(div#id .class).height("30px"))
Edit CSS of Elements in the DOM ($(div#id .class).css("property","value"))
Add listeners for various events taking place in the DOM ($(div#id .class).click(callback))
The most notable of these, of course, is jQuery, and it has one of the largest user bases of any Javascript library. However, it is by no means perfect, and if your library wants to compete, the best thing to do would be to make it excel in the areas that jQuery fails- speed, fragmentation, and "spaghetti" code. (The last two aren't completely in your control, but there are certainly things that you can do to make it easier for users to use the most update version, and keep their code maintainable)
GUI-related (Widget libraries)
I think that this may be the type of framework you're looking to create. These types of libraries provide widgets (datepickers, accordians, sliders, tabs, etc.), interactions (drag, drop, sort, etc.) and effects (show, hide, animations, etc.). For these, people are looking for quantity- the best frameworks out there have several useful widgets/effects that work well. This is one case where it's "the more, the merrier," of course, if it works properly.
Graphical/Visualization (Canvas or SVG related)
The purpose of these libraries is to control animations on the page, specifically on an HTML5 Canvas. These feature animations and sprites for games, interactive charts, and other animations. Again, successful graphical libraries have many, many sprites/animations. For example kineticjs has over 20 different sprites available. However, make sure that quantity does not compromise performance and overall quality.
Web-application related (MVC, MVVM, or otherwise)
Basically, the idea is to provide a layout for the users to put their code in, typically separating the model (data) from the view(what the user sees), with a small controller to provide an interface between these two. This is known as MVC. While it is by no means the only software pattern to base a framework off of, it has become quite popular recently, as it makes development much easier (that's why Rails is so popular).
Pure Javascript- AJAX
This should really be two categories. The first, AJAX libraries, are often paired with a server side library and/or database (though not always) and are designed to make connections with a server and get data asynchronously. The second, "Pure Javascript" are designed to make Javascript easier to program in, as a language, provide helpful functions and programming constructs.
Template Systems
This might also be the type of framework you're looking to create. The idea is to provide components that developers can use. There's a thin line between Template Frameworks and Widget Frameworks (which twitter bootstrap, one of the most popular template frameworks, crosses a lot). While widget frameworks just give a bunch of little elements that can be put in a site, template frameworks give structure to a website (e.g. responsive columns), in addition to making it look good.
Unit Testing
This type of framework is designed to let developers test, or systematically ensure the correctness, of their code. Pretty boring, but also really useful.
Other
This type of framework is for really specific purposes that don't really fit into any of these other categories. For example, MathQuill is designed for rendering math interactively in web pages. It doesn't really fit into any other category. However, these types of frameworks aren't bad or useless, they're just unique. A perfect example is Modernizr, a library for detecting a browser's support for features. While it doesn't really have any direct competitors, can't be put into any of the other categories, and does a very small task, it works very well, and is very popular as a result.
More Types
There are a bunch of other types of libraries. Below are the categories (I'm not listing subcategories because that would take half an hour to copy down) that JSter puts their 1478 libraries into:
Essentials
UI
Multimedia
Graphics
Data
Development
Utilities
Applications
It depends on what you really want. The first distinction that needs to be made is between a Javascript UI framework (which provides structure to the app), an HTML UI Framework (Presentation) and Widget Libs.
Javascript Frameworks such as backbone, angular, ember, and knockout provide MVC-like structure to the app.
UI frameworks such as YUI, bootstrap, and Foundation provide a consistent HTML and CSS base.
Widget Libraries such as jQuery UI, Fuel UX, and Kendo UI provide ready made widgets.
There are also fully-fledged frameworks which provide things across the board, such as Google Closure tools, Dojo with Dijit.
This Wikipedia list pretty much sums it up, and here is the comparison.
In order to find the best way to create a framework, first ask this question: Can any of the above frameworks/libraries solve all or some of the problems/requirements I have?
If something solves all the problems, you can use it right away.
If something solves your problem partially, you can start by extending/forking that project/framework.
Follow DRY and KISS rules. Only solve a problem which nobody has solved as of now.
Fortunately, there is already a good solution: Google Closure Library. This is what Google uses. It shows the approach of mixing HTML, CSS and JS. I wouldn't say it's perfect, but I believe it's one of the best ones at this moment. Its architectural principles rely on proven component based and OOP concepts, and it's accompanied with a static compiler for Javascript. It's definitely worth of studying before baking your own solution.
I'd like to say that cloudcoder2000's answer sums it up nicely. I'm just writing this answer because it didn't seem right in the comment section :P
If you are thinking of making another framework, my suggesting is to stop thinking.
First find the thing in current implementations which troubles you the most, and try to find how you can improve it. Contribute to existing projects, nearly all of them are open source anyways. Also, you don't really need to be a JS-ninja to get into their midst. Take a fork, and get started. Once you're done, and feel that you're code is good enough, make it known to the original repo's maintainers that you have done improvements, and are looking for it to be merged into the project.
Keep in mind here that I'm not discouraging you from solving the problem at all.
I'm just pointing out that there are so MANY frameworks out there, wouldn't it be better if you went ahead and contributed to one of them instead of going for complete glory and implementing a full framework yourself? Making a framework is hard, but getting people interested in your framework is HARD. Really Really HARD, even for Google! Only once Angular got a very good documentation (which itself took quite some time, and resources, of Angular evangelists), that it has gathered so much steam. So, I'm just saying that instead of creating your own monument, perhaps lending a hand to others would be a more worthwhile exercise.
Most importantly though, is the fact that since you are just starting out, I presume you wouldn't have much experience designing frameworks, or thinking in those design terms even. It would of immense value if you contribute to existing projects. Then you will be gathering knowledge and experience of how things are built. Then, you'll be more confident. Then, you can go ahead and make your own framework! Then you'll be more equipped to tackle mammoth projects such as designing a framework. And Then, my friend, will you make something which would be worth the time of countless developers.
Short answer
Build a skinny DOM and only focus on JS code to make it more efficient.
Long answer
A good architect always replies with "it depends." You can't have one single framework that enjoys all others' benefits and suffers from no disadvantages, all at once. There's always a trade-off.
In order to create a framework that is really lightweight, you would probably want the lightest DOM (HTML) structure. However, having a skinny DOM might have the cost of more JS code. So you would probably try to write the most efficient code. You can start here.
Needless to say, you should be keeping the open-close principle, and have the stylesheets separated from HTML, using only classes and never inline styling. I would suggest using less. It makes the implementation faster, and the result is pure css so you suffer from no performance issues around it.
I must respectfully disagree with cloudcoder2000,
From a young age I have been being told don't re-invent the wheel, but why?
During the last 3.5 years, I have re-invented almost all of my web controls using javascript/html/css. From the extremely complex; for example a grid, rich text editor, tree view, dialog. To the very simple, like a progress bar, dropdown. What I gained is a better understanding of html/js/css.
No pain, no gain. I'm so happy with what I was doing these years as I learned more than others.
Some of the controls I re-invented, I think, are much better than the popular ones, like telerik, jquery mobile, extJS. For example, my tree view is fully customizable, with it one can build very complex trees.
So, I encourage you re-invent the wheels, and you will definitely get more than you expected. But also, from the beginning, you need to learn the source code of the popular controls, and re-invent them. You will be very happy when you find yourself be able to make the controls better.
Then the tips on creating HTML controls:
1. use jquery;
2. write jquery plugins(jQuery.prototype...) for simple controls, while define classes for complex controls;
3. separate css from html and js files. Define the html template in js, don't use html files, which make using the controls hard.
Regards,
Leo
For best performance in your UI design, you need to use a lightweight JavaScript framework like angular or backbone, Twitter Bootstrap for the UI, AJAX for base script load and use gzip compression in your app to make it lightweight and help the UI render faster.
I've written a JavaScript application that runs off Prototype & Scriptaculous. I'm thinking of rolling it out in as an open source product & would like it to be able to run on jQuery as well — I typically use jQuery for most of my other apps, except the site this app was originally built for.
I was originally thinking about building two separate applications, but maintaining them would be time consuming. Instead I'm considering building a library abstraction layer that detects if the page is running jQuery or Prototype and then calls the appropriate methods. I'm not going to abstract the whole libraries, just the functionality applicable to my application — namely selectors, events & effect. The core of my app is under 500 lines of code, so there isn't too much I need to worry about.
So instead of calling $('id') I would call LA.$('id') (LA for Library Abstraction) which would call $('id') in prototype and $('#id') in query etc…
Does this sound sane? I can't think of any technical hurdles, although I would have expected someone to have attempted this before. I couldn't find anything similar in my searches.
I expect that if you support the libraries only partly then no one will choose to use it, as they would have to finish the support, and you may find that maintaining it will be a headache, as there will be requests to add more functionality.
If your application is so small, why not just switch to jQuery for it, and standardize on that, as MS has done.
You may run into problems with versions, as, if someone uses it, and they are using an older version of a library, and there was some API change, then they will be wanting you to add support for that library.
I believe Ext.Js does something similar. They have a concept of "adapters" which allow you to sit Ext.JS on top of any of the underlying libraries and it will just work. The key difference is that they are using a 1-to-1 model where you say which library you want to use and it joins the dots, whereas I believe you're trying to say "I don't know which one will be available but whatever one you find, go use it".
I don't think it's insane, but you might have some fun trying to work out which library to use, particularly if both are available.
Web development frameworks (Prototype, jQuery, etc.) themselves are designed to be abstractions on top of the various browsers that exist. You ask the framework to do one thing and it has the same result (ideally) regardless of the browser. So, here, you are proposing an abstraction on top of abstractions. Presumably because you want people to be able to use your tool regardless of what framework they have chosen for their site. While it sounds like an interesting idea, I would personally have to guess that it would not work out in the long run. Largely because you do not know what the future holds. Prototype used to be the number one use framework, now jQuery has surpassed it. Perhaps another one will be very popular in a year, what if you then want to support that framework? That can be a lot of conditional code that you have to add, and in addition, force being loaded into the browsers of those using your tool.
I say either pick a single framework to support and stick with it, or maintain separate libraries. Ideally, it would be really cool if you could write some sort of builder script. This would allow you to set framework rules in some list and the script would build separate scripts for each framework based on some core script and the rules list. I honestly am not sure how to best accomplish something like this but it would effectively give you that abstraction on abstraction power that you are looking for without it being visible to the end user.
Is it good or okay to have several frameworks in a project, or is it bad because it gets cluttered (= a mess), and the loading times maybe get's longer. Does some 100 K matter really? Or should you stick with one?
It's generally better to pick one thing and stick with it, for a number of reasons:
Fewer dependencies.
Lower complexity.
Easier to maintain.
Faster loading times.
No likelihood of dependency conflicts (i.e. jQuery can't conflict with your other Javascript framework if you only have one).
Lower debugging times.
It's true that an extra ~50k these days probably isn't going to kill anybody for a personal site or blog. The benefit comes when you scale to larger sizes, and all those extra 50k hits are eating into your bottom line. But even if you're just doing this for a small site, the savings on your sanity from figuring out problems quicker will easily be worth it.
That said, if you just need one part of a specific piece of a Javascript framework, the larger ones are often split into logical chunks, so that you can just take the piece you need rather than the entire framework. Most are rich enough these days that if framework X has a feature you want, but you're using framework Y, you can pretty much just map the source code for that feature directly into framework Y.
If you can load the javascript library from a repository where it would be cached on the first visit, then i don't really see any problem with that.
But, for uniformity sake i will go with one javascript library.
But, if you really have any strong reason to use two, then go ahead. As far as it is cached the first time.
Just adding something to John's words, one could choose, for example, JQuery, which allows you to use it without clashing with other libraries. I remember that once, I had troubles while trying prototype and mootools because I wanted some things from the former and some other from the latter, but it was long ago and maybe it was solved.
Somehow, I've found that it's easier to maintain a single library and there're a few real differences between them. It related more to the way each one approaches to map documents and apply things to their elements, which causes differences in response time, but the goal happens to be the same.
Good luck with your choice :)
PS. If you gzip and fix etags in the stuff you offer in your webapps, the difference between loading one or two js frameworks is not reeeeaaally important -unless you're in facebook, meebo or so!-. I've found that the yahoo! recommendations are helpful.
http://developer.yahoo.com/performance/rules.html
I wouldn't run two frameworks unless there was really no alternative. They often aren't written to play well with others; there are lots of potential ways they can cause unwanted interactions.
For example with jQuery, a lot depends on the user-data key identifiers the library adds as attributes to element nodes. If you start messing with the structure of the document by cloning, adding/removing and so on from another framework (or even just plain DOM methods) then those identifiers aren't as unique as jQuery expects; it can easily get confused and end up failing to call event handlers, or tripping on errors. This sort of thing isn't fun to debug.
I've started looking into architecturing a javascript framework.
I don't want to reinvent the wheel here, especially regarding browser quirks, and know that for that matter, I'll have to rely, at some point, on some commonly-used libraries to handle low-level concerns.
The thing is, I'm not sure how i can depend on an external library for some piece of functionality (say for example dom manipulation), without tying it to my design.
Practical examples would help make a better point, but I'm not at the design stage yet, and I'm merely trying to avoid getting started on the wrong foot.
So I'm looking for some examples, guidelines, best-practices or maybe patterns that could help in this situation.
Any insight ?
EDIT : Bit of a clarification on why I'd want to do this.
My goal is to build something resembling more of an application framework than most traditional libraries like jQuery.
Think layered architecture, where the libraries would fit into the infrastructure layer (as per Evans' definition in Domain Driven Design), and handle things such as events, dom traversing and manipulation etc...
This is a very broad question, but if I were you, I would use jQuery as a base. It is a very easy library to extend and add functionality too.
I'd recommend grabbing a copy of ExtJS and taking a look at how they provide support for replacing the underlying core of their product. You can use their higher level libraries, such as grids, trees, etc, but choose to use YUI or prototype in place of their Ext core.
That should give you a good starting point.
Edit to answer comment:
Once you've downloaded ExtJS, take a look in the "adapter" folder. In there, you'll see the various adapters that exist to make ExtJS work with other libraries. You'll quickly see how they define functions that in turn make use of the appropriate underlying lib.
Segregate your code:
use the external libraries to the fullest possible, within their separate section of code.
Taking jQuery as an example, just designate a section for interfacing with jQuery and then use jQuery within that section of the library like there's no tomorrow, and give it interface functions that the rest of the code uses exclusively.
Frankly, if you integrate a library with your code and try to make it generic enough that you can trivially swap it out with something else, you're probably going to neuter the library to the point where you might as well have not included it at all.
Accept that you may need to rewrite if you end up swapping libraries, but prepare for that by giving the library-interfacing code it's own separate section, and you'll be able to write less generic, more powerful code with those external libraries and save yourself a lot of work.
This doesn't answer your pattern question, but a word about the frameworks. All of the modern JavaScript libraries are pretty good at playing well with each other, but some are better than others. Just make sure that they libraries don't monkey-patch the core objects with arbitrary properties or muck with the global namespace and you should be good to go. JQuery and YUI are both well designed and namespaced libraries. Dojo is also quite good, but a couple years ago when looking at all of the options, it seemed like Dojo encouraged the use of proprietary element attributes in markup as JS hooks. At that time Prototype was the library that mucked with objects like String/Array and didn't play well with others. I haven't looked/used Dojo or Prototype so take that with a grain of salt. I'm actively using YUI and JQuery in the same app; YUI for widgets and event management and JQuery for Selector/DOM manipulation.
I'd suggest you pick a single general purpose library or no library at all, depending on the requirements of the framework you plan to write. It's very difficult to make any kind of recommendation without more information, such as what your framework is aiming to achieve, who will be using it and in what kind of environment.
If you're considering writing a script of reasonable complexity then I would suggest learning the relevant "low level" DOM manipulation techniques for yourself. It's not as difficult as devotees of some of the famous general purpose libraries would have you believe.
Use some kind of interface to link to the library.
Don't do:
$("blah").something();
do
something("blah")
function something(id){
$(id).something();
}
Since you could call something() 20 times, it'll be simpler to update if the actual use of the library is in only 1 place.
It'll add development time and then complexity, but you won't be as dependent on a library.
I don't think this can be achieved very effortlessly. If you really want this behavior, I think you'd have to manually map the features that are covered by all libraries you want to include support for.
So that the implementation would look like:
yourLibrary.coreFramework = 'prototype';
yourLibrary.doStuff();
And your librar would treat it in the following manner:
function doStuff() {
var elem = getElement('id');
// do stuff with 'elem';
}
function getElement(id) {
switch(this.coreFramework) {
case 'prototype': return $(id);
case 'jquery': return $('#'+id);
/* etc */
}
}
Check out the jQuery or prototype frameworks.
If you decide you need to, then extend these.