7 ms·

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 a

by cryptoz 12y ago

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 http://i.imgur.com/CHOFGML.png

diminoten 12y ago
But Genius is the Next Big Thing! You must like the Next Big Thing!
jasonlotito 12y ago
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.
- hiby007 12y ago
  I am facing the same problem. I am going back to top of the page when I click on the long block of code.
- sic1 12y ago
  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.
- glossybrown 12y ago
  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.
  - pests 12y ago
    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.
nostromo 12y ago
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?
- markm208 12y ago
  There is something that I have been working on: https://vimeo.com/97711978#t=0m37s https://vimeo.com/97711978#t=0m37s
- ThrustVectoring 12y ago
  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.
- OvidNaso 12y ago
  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/ http://orgmode.org/worg/org-contrib/babel/
- jostylr 12y ago
  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 https://github.com/jostylr/literate-programming-lib
toxican 12y ago
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?
- metamet 12y ago
  Why they did it this way and not like their other branches makes no sense. See: http://genius.com/Kendrick-lamar-king-kunta-lyrics http://genius.com/Kendrick-lamar-king-kunta-lyrics
maxmcd 12y ago
This formatting style for annotated sources always seems to work so well: http://robflaherty.github.io/jquery-annotated-source/docs/01-core.html http://robflaherty.github.io/jquery-annotated-source/docs/01...
- gearhart 12y ago
  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...
- Mahn 12y ago
  Seconded, if you are going to annotate source code please go for this format.
- lelandbatey 12y ago
  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/ http://jashkenas.github.io/docco/ [1] - https://github.com/fitzgen/pycco https://github.com/fitzgen/pycco [2] - http://rtomayko.github.io/rocco/rocco.html http://rtomayko.github.io/rocco/rocco.html [3] - http://rtomayko.github.io/shocco/ http://rtomayko.github.io/shocco/ [4] - http://jashkenas.github.io/docco/#partners-in-crime- http://jashkenas.github.io/docco/#partners-in-crime-
  - nosefrog 12y ago
    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 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/ https://srclib.org/
TeMPOraL 12y ago
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.
Eyas 12y ago
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.
- darklajid 12y ago
  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.
  - Eyas 12y ago
    Agreed. Just separating concept from implementation.
- dragonwriter 12y ago
  > 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.
StavrosK 12y ago
This looks like an ad for Genius, though, so that'd be why.
- hamburglar 12y ago
  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.
  - krick 12y ago
    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.
    - itsbits 12y ago
      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.
- AwesomeTogether 12y ago
  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
stronglikedan 12y ago
It would be nice if you could simply drag the modal once it's rendered. I think that would be the most simple solution.
- oneeyedpigeon 12y ago
  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 :)

by cryptoz 12y ago

diminoten 12y ago

But Genius is the Next Big Thing! You must like the Next Big Thing!

jasonlotito 12y ago

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.

hiby007 12y ago
I am facing the same problem. I am going back to top of the page when I click on the long block of code.
sic1 12y ago
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.
glossybrown 12y ago
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.
- pests 12y ago
  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.

nostromo 12y ago

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?

markm208 12y ago
There is something that I have been working on: https://vimeo.com/97711978#t=0m37s https://vimeo.com/97711978#t=0m37s
ThrustVectoring 12y ago
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.
OvidNaso 12y ago
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/ http://orgmode.org/worg/org-contrib/babel/
jostylr 12y ago
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 https://github.com/jostylr/literate-programming-lib

toxican 12y ago

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?

metamet 12y ago
Why they did it this way and not like their other branches makes no sense. See: http://genius.com/Kendrick-lamar-king-kunta-lyrics http://genius.com/Kendrick-lamar-king-kunta-lyrics

maxmcd 12y ago

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

gearhart 12y ago
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...
Mahn 12y ago
Seconded, if you are going to annotate source code please go for this format.
lelandbatey 12y ago
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/ http://jashkenas.github.io/docco/ [1] - https://github.com/fitzgen/pycco https://github.com/fitzgen/pycco [2] - http://rtomayko.github.io/rocco/rocco.html http://rtomayko.github.io/rocco/rocco.html [3] - http://rtomayko.github.io/shocco/ http://rtomayko.github.io/shocco/ [4] - http://jashkenas.github.io/docco/#partners-in-crime- http://jashkenas.github.io/docco/#partners-in-crime-
- nosefrog 12y ago
  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 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/ https://srclib.org/

TeMPOraL 12y ago

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.

Eyas 12y ago

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.

darklajid 12y ago
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.
- Eyas 12y ago
  Agreed. Just separating concept from implementation.
dragonwriter 12y ago
> 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.

StavrosK 12y ago

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

hamburglar 12y ago
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.
- krick 12y ago
  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.
  - itsbits 12y ago
    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.
AwesomeTogether 12y ago
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

stronglikedan 12y ago

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

oneeyedpigeon 12y ago
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 :)