I could have really done with this a few months ago. I was trying to make animations of electrons flowing through wires of variable thickness, and really struggled trying to find examples online. I ended up having a three hour maths lesson with my brother over irc, to get my head around vector maths.
Annotated code: Circles bouncing off lines
41–50 of 70 posts
Re: Annotated code: Circles bouncing off lines
#42I hate this left/right code documentation fad with passion. Making my eyes jump horizontally across the page every few lines is about the worst you can possibly do for readability. Just keep the damn comments inline and use colors/font-faces/fold markers to make it readable.
I find it far more readable. Anyway, next to where you clicked Annotated Code there's a link for Raw Code which has the comments in-line if you prefer that. You can use an IDE or web editor to get the font colors nice.
Re: Annotated code: Circles bouncing off lines
#43Earlier quoted context omitted.
Do you also prefer footnotes and sidebars inline when reading articles? These are standard typographical practices. I do set my comment color to super light so comments don't distract me too much when reading code, but I wish there was a better way.
Not the parent, but I prefer footnotes/sidenotes when reading physical texts, but prefer inline commentary when reading on the computer screen. Jumping up and down to read a footnote (either manually scrolling or with a hyperlink) or having the sidenotes take up a large percentage of the screen is disorienting for me. It helps if the inline commentary is differently colored or in a separate box. I also use light colo…
That is why side notes are so nice: you don't have to scroll down, you just look at the side bar. And if you just want to read code...hide the side bar! Horizontal real estate is not a big deal with 80 column code widths (you could even have two or three screens of code on one monitor still). Heck, you could render the comments with a proportional font to save even more H-space (fixed-width fonts are extremely archaic).
Programming should move out the typographical stone age into something a bit more modern.
Re: Annotated code: Circles bouncing off lines
#44Earlier quoted context omitted.
Why are people trying to make comments disappear? They are there for a reason. I agree with what moe is saying, though not moe's tone.
Comments get in the way of the flow in reading code; they are often of little value that easily goes negative when they distract.
My biggest pet peeve is docblocked-to-death code, like
class Widget
{
/**
* @access public
* The name of the widget
*/
public $name;
/**
* @access private
* The widget's material composition
*/
private $composition;
// ... yada, yada ...
}
Re: Annotated code: Circles bouncing off lines
#45Trying to keep the narrative of explanation in the same linear order as the code makes for a surprisingly difficult to understand item. Would be neat to see more "traditional" literate programming techniques applied here. All of that said, really cool, and seriously thank you for sharing!!
I wonder if the weaving in literate code is one of the things that could only have been invented to deal with Pascal. It is useful to be able to rearrange the presentation even in JavaScript, but I doubt it would be enough of a pain point for people to invent weaving in an alternate history were literate programming was born on more flexible languages.
I wrote a literate-programming compiler to deal with JavaScript programming (any language works, but js is the one I use the most); it use markdown as the language in which the code is embedded.
For me, prototype setup and async stuff seemed to naturally lead me to want to differ in the ordering between how I write and how the program is laid out. I find it quite liberating to not care what order I write the code in, dashing off a substitution section to deal with later.
I know functions can be used to chunk out code in different orders, but I like the interplay of having it ordered in the writing in a sensible fashion while still getting the compiled view of it in the programmatic ordering.
Plus my version allows for a lot of finely tuned hacking on the language. That is, one can reduce a lot of boiler-plate setup with processing small chunks of code.
Having said all that, I would not use Knuth's original version for js. I think what was particularly attractive was a simple language like markdown for embedding code in a natural and simple way.
My main repo is https://github.com/jostylr/literate-programming though I am currently rewriting the engine behind it to allow for more asynchronous compiling https://github.com/jostylr/literate-programming-lib
Re: Annotated code: Circles bouncing off lines
#46In case anyone wonders about that reverse-for loop in updateCircles():
Iterating over an array in reverse allows you to remove items in the same iteration (at the very end of the loop). If you delete an item, the items which follow are downshifted by one which means that their indices also change.
However, this isn't a problem if you iterate in reverse, because you already took care of those items in previous iterations. The item you'll handle next will stay where it is.
This also works nice with unordered lists (or "bags").
Re: Annotated code: Circles bouncing off lines
#47Here's a similar effect, from a 1994 C64 demo.
Re: Annotated code: Circles bouncing off lines
#48Earlier quoted context omitted.
Not the parent, but I prefer footnotes/sidenotes when reading physical texts, but prefer inline commentary when reading on the computer screen. Jumping up and down to read a footnote (either manually scrolling or with a hyperlink) or having the sidenotes take up a large percentage of the screen is disorienting for me. It helps if the inline commentary is differently colored or in a separate box. I also use light colo…
That is why side notes are so nice: you don't have to scroll down, you just look at the side bar. And if you just want to read code...hide the side bar! Horizontal real estate is not a big deal with 80 column code widths (you could even have two or three screens of code on one monitor still). Heck, you could render the comments with a proportional font to save even more H-space (fixed-width fonts are extremely archai…
I see where you're coming from regarding ease of hiding/unhiding comments, but I think it'd be quite hard to do correctly in user configurable environments.
In the article, I'm assuming the left column takes up a bit less space on the author's browser viewport, but it takes up about 45% of mine, while a bit of the code trails off the page.
The reason I think it works so well with physical books is that the dimensions are known and not user-configurable, so it's easier to guarantee that the sidenotes look appropriate. With free-form comments that could range from a one-line comment to large paragraphs to explain one line of code, I don't think there's a way to make sure they would look reasonable in all cases. (I could be wrong)
A good example of easy-to-read in-text notes (in my opinion) are those in Fred Hebert's LYSE [1]. They could be sidenotes or footnotes, but instead they're in-text, which makes them easier for me to read in a browser, regardless of screen size, but also pretty easy to skip over since they're color-coded and in their own box.
I think it's more of a medium difference than a book-typography-is-more-modern one. When scrolling through a web page or code, I mostly find the single-column in-text notes/comments easier to use, though I see why some people might prefer sidenotes.
[1] http://learnyousomeerlang.com/starting-out-for-real#bool-and...
Re: Annotated code: Circles bouncing off lines
#49I assume the side-by-side view is rendered from the raw file with comments inline? Is this using some kind of comment markup language?
Where can I find out more about cool ways to render comments like this?
Re: Annotated code: Circles bouncing off lines
#50I assume the side-by-side view is rendered from the raw file with comments inline? Is this using some kind of comment markup language? Where can I find out more about cool ways to render comments like this?
It's generated using http://jashkenas.github.io/docco/. I think it's possible to use comments, but often it's "literate" source code, e.g. markup & code blocks.