John Resig annotates original jQuery source code | Hacker News Reader

John Resig annotates original jQuery source code

genius.com

523 pointstomlemon97 comments

Very neat content, but does it have to be formatted like this? I respect that it preserves the original file, but it makes it very difficult to read. Comments added to the source code would serve much better for the purposes of understanding the code.

This tool makes it impossible to read the annotation and the source code at the same time. Clicking on 'set' for example, about 20-30 lines in, lets you read the annotation, but not the function. You have to hide the annotation to read the code.

Wouldn't inline/multiline comments be so much better than this?

Edit: Citation/example: http://i.imgur.com/CHOFGML.png

Came here to say this. I cannot fathom how this is considered usable at all. There are also times that you click on the block of code to read, and it sends you back to the top of the page.

I'm more interested now in how this application got pushed to production in its current state.

I am facing the same problem. I am going back to top of the page when I click on the long block of code.

I just want the comments in a fixed window that is draggable so i can put it where i want. I think that would make everyone happy...or at least be better.

Great content tho, enjoying the read.

Sorry about this bug! We're working on a fix now.

Definitely one of the biggest challenges in building this product is getting the annotation interface to work consistently in a “host page” environment over which we have pretty much no control or advanced knowledge. So for instance, the jump-you-to-the-top bug isn't something we've seen in the general case; we're currently getting to the bottom of why it's happening on this particular page.

I noticed it happened on the last annotation that was at the edge of the screen. It looks like you position the annotation box at this height. That might have something to do with it.

Also, after a long piece of annotated text its annoying that the box pops up at the very bottom of the text rather than side by side.

I like it. It almost makes me wish I could comment my code like this somehow.

I often find that long comments can break my flow when reading code -- but of course, commenting is necessary, so perhaps it could be useful to pull them aside in an IDE. Does something like that exist?

There's likely some way to have Vim automatically fold and hide comments. Then, they're one line when not needed, and a `zo` away when you want to read them.

There is something that I have been working on:

https://vimeo.com/97711978#t=0m37s

Isn't this sort of the original intent and purpose of Literate programming. I just spent a bunch of my time creating my emacs configuartion in org-mode using babel [0] and man, it was a cool experience. You can comment out the wazoo, linking to the web, other files or other parts of the same file all organized in a custom hierarchy or whatever you choose.

Then just C-c C-v t and all the source code is in a clean seperate file. You can even set it up to include the comments, link to the comments, or whatever other way you want the output to be. If I ever pursue programming more seriously, I can't image not seriously trying to do it in this manner.

0. http://orgmode.org/worg/org-contrib/babel/

I wrote a markdown based version of literate-programming that allows one to write it with lots of comments and organize the code in anyway you wish. But then when compiled, you can see all the code without all the long comments. You can still have normal programming comments in there, of course, but the detailed thinking (the why and an overview of relations to other parts) can be taken away.

https://github.com/jostylr/literate-programming-lib

I like the cleanliness of how it is now and I like the preservation of the original file, BUT the annotations seem to pop up wherever they want to without rhyme or reason. Why not just have them pop up on the right side of my screen? Or have a dedicated annotation block that scrolls with me, but well away from the content itself?

Why they did it this way and not like their other branches makes no sense.

See: http://genius.com/Kendrick-lamar-king-kunta-lyrics

This formatting style for annotated sources always seems to work so well: http://robflaherty.github.io/jquery-annotated-source/docs/01...

Absolutely agreed - I just had to click 40 times to read 40 comments when I had half a screen's worth of whitespace they could've just been sitting in...

Seconded, if you are going to annotate source code please go for this format.

Indeed, that side-by-side annotated style is great. For those who would like to create similar pages, the original program is Docco[0], a Javascript project. However it's been ported over to many other languages and can be found in these projects:

- Pycco[1] Python

- Rocco[2] Ruby

- Shocco[3] POSIX Shell

- Many more, as found here[4]

Note each of these projects support highlighting different languages. For example, the Pycco[1] project uses the Pygments library for language handling, and thus supports many different languages. Others, like Shocco[3] only support one language (Shell in the case of Shocco).

[0] - http://jashkenas.github.io/docco/

[1] - https://github.com/fitzgen/pycco

[2] - http://rtomayko.github.io/rocco/rocco.html

[3] - http://rtomayko.github.io/shocco/

[4] - http://jashkenas.github.io/docco/#partners-in-crime-

I agree, Docco-style docs are really easy to read.

I built srcco, a Docco-style doc generator that links every variable, function, etc. within your project to its definition (similar to sourcegraph.com -- full disclosure: I work at Sourcegraph), to demonstrate how to build things on top of our free/open source language analysis framework, srclib[0].

You might find it interesting (the links in the code have white backgrounds): http://sourcegraph.github.io/srcco/srcco.go.html

It only works for Go because the only Go toolchain keeps track of comment ranges (because srcco removes the comments from the source code), but it wouldn't be too hard to add comment ranges to the other toolchains. If you are interested in language analysis for languages like Java, Python, Haskell, or Javascript, I would be happy to help you make your first contribution. Ping me: samer@sourcegraph.com.

[0] - https://srclib.org/

Here's also a Docco 'implementation' for Java code: https://bitbucket.org/doklovic_atlassian/atlassian-docco

Strangely, the "default" Genius UI seems to be more or less the two column view - e.g., http://genius.com/1258740/Walt-whitman-song-of-myself/I-cele...

Is this intentionally divergent or is it some kind of bug?

Still just as bad tbh, you still need to click through every annotation.

What is the tool that produces this?

The Docco ( http://jashkenas.github.io/docco/ ) family of tools.

I think this wouldn't work for anecdotal comments that John is doing here which runs into paragraphs which would result in lot of whitespace on the right. I think an easier fix would be to highlight the current annotation in a different color while docking the comments to the right while keeping it free for user to move around.

I agree that clicking to go to next is annoying. Perhaps mouse over or scrolling should automatically show the annotation.

I built https://notedcode.com a while ago. It sets comments in any repo on GitHub or Bitbucket alongside the original source, and allows you to add and share further annotations, keeping them alongside the right section of code even when the code changes.

IMO this is cool, but it would be even better if it was in the right margin, so it wouldn't overlap with and hide the code.

This looks like an ad for Genius, though, so that'd be why.

If it's supposed to be an ad for Genius, it's a pretty lousy one, in my opinion. Half of the time I click on a highlighted line, it opens the annotation and then scrolls away, so I can't see it. It's pretty frustrating. And the "view on Genius" link redirects to the top-level Genius.com page, which just makes me sigh and close the window.

Doesn't matter. People will be like "Oh! John Resig uses Genius! Looks like that's actually real software for the cools guys, not some stuff nobody uses."

Usability is optional for that.

naah..its only for sometime. Agreed that people surely gonna have a look on it since JOHN RESIG uses it but usability only helps you to keep on using it.

genius is based in New York I think, and so is John Resig (at least at lot of the time, he attends JS meetups in New York). He's probably doing them a favor, although the founders of genius are rather obnoxious and John's just the opposite, so it's not whom I'd expect him to help out. Maybe he's going for funding from Horowitz, who also funds genius

The main difference between Genius-style annotation and code comments, which I think is important to note (and valuable) is that code comments annotate a point or position in the source, while genius annotations are referring to a span or range in the source.

Well, I think the idea is sound. I'm even into Hip-Hop/Rap, so I should like them.

Unfortunately the user interface is a world of pain. It's unusable. It's worse than quora. Good idea, but the execution needs work.

Agreed. Just separating concept from implementation.

> The main difference between Genius-style annotation and code comments, which I think is important to note (and valuable) is that code comments annotate a point or position in the source, while genius annotations are referring to a span or range in the source.

I don't think that's necessarily true; code comments very often refer to a range in the source. Because code is generally designed to be accessed as linear text without hyperlinking facilities, the identification of the range is usually something that the reader has to interpret by applying (sometimes language specific) conventions relating to code formatting, indentation, and the precise placement of comments, and there are a limited set of kinds of spans that conventions cover (e.g., a span that starts in one block but extends to include the following part of the containing block doesn't have a good layout convention to indicate that a comment goes with it.)

Genius-style annotations, because they aren't limited to conventions that work in a strict linear text medium, can easily refer to arbitrary spans of content.

It would be nice if you could simply drag the modal once it's rendered. I think that would be the most simple solution.

Exactly what I was thinking. I'm sure there's some kind of cross-browser, front-end javascript library that you could use to achieve this :)

It's very kind of John to mention my first jQuery plugin in the notes.

Unfortunately, it was not a very good plugin and probably set a bad precedent.

Like so many new jQuery developers, I went "Chaining? Whoa. Chain all the things!"

So I attached the plugin to $.fn, not thinking about the fact that what the plugin did had very little to do with the current element selection.

I may have been the first to make this mistake, but at least I wasn't the last. :-)

Perhaps I redeemed myself by coming up with the idea to use $.prototype for plugin methods instead of copying the method references by looping through $.fn (we kept $.fn as an alias of $.prototype for compatibility). So a $(...) call became a lot faster.

I suspect a lot of the "unnecessary chaining" that occurs is really a problem of people (A) making something that requires jQuery and they don't want to think about how to ensure that dependency, while (B) liking the idea of associating their little thing with a big-name project.

Then you get things like $("#target").MakeBobsFancyBoxWidget()

What surprises me is the lack of comments in the original file. This leads to e.g.:

    this._get(i).$$tmpFunc = f;
    this._get(i).$$tmpFunc(i);
    this._get(i).$$tmpFunc = null;

with the comment (from now):

So this may look crazy — it certainly does to me! Why not just do: f.call(this._get(i))? If I remember correctly, and I just did some double-checking and I think this is the case, but IE 5 didn’t support .call()! The original version of jQuery event worked back to IE 5… I can hardly believe.

I personally hate coming across snippets of code like this (usually from myself ): ). What do I do here? Can I just replace this with .call? Why did he not do .call? Performance? Or just MSIE5 (if I ever figure that out in the first place).

All my respect to mr. Resig, of course! What an almost legendary piece of software. Just interesting to see that this commentless programming is something of all pedigrees.

And a note to people saying "learn from this," please also learn that without the original author and rapgenius, we would never have understood that part. Or at least I wouldn't.

Absolutely agreed - comments are so important! Seemingly when I was working on jQuery alone and without much feedback I was totally fine just having no comments. I noticed that in the subsequent releases of the code that the number of comments quickly rose - likely as people started to use the library I felt bad that the code was so poorly explained!

I still have 0.3 in my code base, and there are some gems like:

     // Arrrrghhhhhhhh!!
     // I overwrote the event plugin's .load
     // this won't happen again, I hope -John

BTW, do you know what happened to Dean Edwards. He was doing some really interesting work around the same time as you.

Also with all my respects to mr. Resig, but this is not really code to learn from. It's full of bad habits and it's hard to read. Poorly named, mostly uncommented and pretty hacky.

Not really judging, it was just a bunch of handy hacks he had for personal use.

Another reason it's hard to follow is of course: writing a CSS selector is not a trivial task, and that with all the browser quirks workarounds. I'm sure getting it working properly wasn't a walk in the park.

That said, he often talks about how he wanted to make the code look "cute" by making it as compact as possible and to save weight. Although weigh matters a lot in the web, the source code is a terrible place to optimize. Instead, write readable code, with sensible names, and then compact it with tools.

I completely agree. I tried to make a bunch of notes on the (poor) code quality, inline. This is mostly an attempt at archaeology, if you will. Naturally the current release (or even 1.0 release) of jQuery is substantially better code in every respect.

> and then compact it with tools.

Did we have minification tools back then?

Jepp: http://www.crockford.com/javascript/jsmin.html

    this is not really code to learn from

I used to work with someone who could look over my shoulder, read and evaluate my code, and then tell me where my bug was within seconds. He knew the code better than I did, and I'd written it! I asked him about this mad skill of his and he directed me to easily the worst programme I've ever read in my entire life. [1]

It was a block of unformatted, uncommented, dangerously typecast old-style C, with meaningless single letter names for variables and functions.

So I read it. It took a lot of study and I didn't cheat and run it through a pretty printer. I never really got to the point where I grokked it but my ability to read other code has improved a lot.

So whilst I agree that it's important to write code in the way you describe, I think it's well worth reading code that takes you out of your comfort zone from time to time.

[1] http://keiapl.org/rhui/remember.htm

The annotations are also a great reminder of how programming used to be not so long ago. It's hard to imagine having to search Internet Archive for your own source code in this age of Github:

http://genius.com/5088475

> Note: This may not be the first first code released, but it appears to be the earliest copy that we’ve found, so far. This is a copy that was indexed by the Internet Archive on Feb 3rd 2006, so about 2.5 weeks after the initial release. It’s very likely that a few things changed in that time period and I’ll try to make a note of some of those, that I can remember, inline.

I'm sorry, but this has to be said. This guy loves exclamation points! Almost every paragraph features one. It reminds me of a great Seinfeld episode:

Jake: Well, maybe I don't use my exclamation points as haphazardly as you do.

Elaine: You don't think that someone having a baby warrants an exclamation point.

Jake: Hey, I just chalked down the message. I didn't know I was required to capture the mood of each caller.

Elaine: I just thought you would be a little more excited about a friend of mine having a baby.

Jake: Ok, I'm excited. I just don't happen to like exclamation points.

That's just negation in JS.

Well played.

John also spoke at the March Code Genius. You can check out his full talk here: https://www.youtube.com/watch?v=H4sSldXv_S4

Anyone else already find the XSS in genius.it?

Edit: wow, the whole thing is seriously broken. Emailing them now.

Edit 2: It's not as broken as I thought, and these guys are quick to reply and try to figure things out. To be clear, I haven't gotten it to run arbitrary JS, just include arbitrary HTML, which isn't as dangerous.

Let us know this'd be very helpful! tom@genius.com

Emailed.

BTW would really love to link to a particular annotation.

I noticed it when http://genius.com/5104616 was broken where John included the <div> tag.

How is including arbitrary html not as dangerous, when arbitrary html also means <script> tags?

I'm not sure what exactly he's referring to, but annotations allow you to use markdown and some (limited, heavily sanatized and whitelisted) html, so that could be what he was talking about.

heavily sanitized and whitelisted html isn't really arbitrary, is it?

To clarify, it appears that both genius.it and genius.com use Markdown which allows HTML. Their code sanitizes it, so that you can't include attributes of tags, and you can't include certain tags such as <script>, <style>, <link>, or <meta>. I spent about 10 minutes on it and could not break it. That isn't to say it cannot be broken, just that it's not wide open and obvious attacks are mitigated.

I was able to XSS myself: when I added certain types of malicious code it did execute, but if I reload the page the malicious part is not rendered. In other words, it's filtered on the output, not input, and the rendering is different for content fetched from the server vs content you just created. You can execute code in your own browser, but not for anyone else (as far as I was able to).

Their team is very responsive and took my concerns over this seriously.

>Anyone else already find the XSS in genius.it?

This is a sandboxed domain, like googleusercontent, so not a bug. XSS on genius.com would be a vulnerability.

Though Resig's anecdotes are fun and interesting to read, it doesn't help that much with understanding the actual source code. Here's a better version in terms of readability and depth:

https://robflaherty.github.io/jquery-annotated-source/

https://robflaherty.github.io/jquery-annotated-source/docs/0...

Sadly, no longer updated since jQuery 1.6.2 which was released in 2011.

Out of curiosity, do you know of any other ubiquitous projects that have had a similar treatment?

CoffeeScript's source is annotated in the same way.

Backbone, Marionette and Underscore all have annotated source like this linked on their project websites.

The comments in the current jQuery source are pretty good about explaining the strange things that need to be done to work around bugs in browsers. Look for the `// Supports:` comments.

Wow, makes me feel a little better that he had 75 open source projects before he had a 'hit'. :)

where did you see that ?

It was stated in one of his annotation

Maybe I missed the release announcement on this genius.it thing but thats the real story

http://genius.it/https://news.ycombinator.com/item?id=933629...

If you're a new or relatively new developer I highly recommend reading through things like this. All too often developers get in the habit of writing a lot of code without also reading what other more experienced developers have written.

Amazing that it has been more than nine years since the original release (Jan 14, 2006)!

How long did it take for John to write this initial version? Any idea?

I don't have exact records but based upon what I was inspired by, and what else I was working on at the time, it roughly equates to the fall of 2005. I was in college at the time and taking classes so I was working on it on-and-off as my schedule allowed. I finished it up over winter break and went with some friends to BarCamp NYC 2006 and released it there.

Thanks John, always good to hear straight from the horse's mouth!

on mobile: i only see the code. sigh. why even serve me a different page? I'm running full blown Firefox.

So glad jQuery came along and became what it is. Scary to think of a world where it was just bundled alongside Prototype. For those not versed in Prototype, those were dark days (at least for me).

I always kind of wished that MooTools had won out in their battle to overtake Prototype's crown. It had a much more sensible namespace, and focused much more on solidly structured code over "how short can I make this".

Is there a list of other source code annotations on Genius? Their "tech" section of the web site is full of crappy startup news and doesn't even link to this gem.

  if ( !b )
    for ( var j in a )
      this.style[j] = a[j];
  else
    this.style[a] = b;

I really dis-liked having unnecessary braces. This… unfortunate… style preference plagued us for quite a while and caused all sorts of avoidable logic errors.

I really wish this kind of coding was removed completely from some languages.

I found myself wishing this was a screencast.

Paul Irish has done a few videos where he walks through some of the jQuery code: http://www.paulirish.com/2010/10-things-i-learned-from-the-j...

I can't believe that article was five years ago already! >.>

Anyone knows if there are outdated sites that still using early versions of jQuery? =))

I don't have any links off-hand but I know that there was a Nintendo.com sub-site that was using a pre-1.0 version of jQuery. Even though the overall code quality is rather low it did have decent browser support - unless browsers actively begin breaking their APIs (unlikely) those old versions of jQuery will probably keep working forever!

I've archived the original 2005 jquery script (aka jselect) https://github.com/daniellmb/jquery-archive

Firefox 36, OS X. This doesn't seem to be working for me at all.

I would actually like this in an IDE. Visual Studio kind of does this with header comments but it would be great to be able to show/hide comments with links, rich text,...

Vim's folding doesn't do this out-of-the-box, but you can set it up to do so. Clickable links aren't doable, though copying and opening in a browser tab is something like seven keystrokes on my current setup.

In modern Vim (with netrw), you can type `gx` when the cursor is over a URL to open it in your browser.

Kind of surprised Sublime Text 2 / 3 doesn't have a plugin that allows for annotation.

You might want to check this out: https://srclib.org/plugins/sublimetext/

srclib is the open-source library that powers Sourcegraph, a code search engine.

What's the standard the Genius uses to perform annotations? Anybody know?

It's 500'ing for me, anyone else seeing this?

would love to see a frontend framework that uses jQuery syntaxes only.

Reply on news.ycombinator.com