Comments/code side-by-side view

[sindresorhus]

We've been thinking about how we could make it easier for users to quickly go through an app and understand it. One is better code comments #385.

Another is http://www.explainjs.com which does something interesting by extracting the code comments and showing them besides the code Docco style. We should think about doing something like this ourselves. Though we would need some kind of simple file browsers since an app contains multiple files. I would also like syntax highlighting. We could use the explainjs API or host something ourselves.

Let us know if anyone is interested in prototyping something like this.

Thoughts?

[stephenplusplus]

I like this, I'm only weary of sending learners to another place than the demo or the source code itself. I think there's more we can do within the app to make learning easier. All of my ideas tend to be way too big to implement, and this will probably be another one...

Make use of the console. In the code, place debuggers where interesting things are happening, and a matching comment above the debugger explaining why we wanted your attention. I'm not sure how debuggers behave in all browsers, but for Chrome, if you don't have the console open, the app won't break.

If we wanted to go even further, we could use a simulated "debugger," say "tasteBugger" (ha), and display messages/code in the app itself. That way, if the console isn't open, the user still has the benefit of feeling like they're on a tour.

Rough pseudo implementation.

tasteBugger = function (msg) {
  var tasteBugger = document.querySelector('.tastebugger');
  tasteBugger.innerHTML = msg;

  // You've hit a breakpoint! Step through the callstack to see how we got here.
  debugger;
};

var saveTodo = function (input) {
  // Before saving the todo, trim the input to avoid empty todos.
  input = input.trim();

  if (input) {
    // Call the save method on our Model, which will update the record in localStorage.
    // Type `Model` in your console to see the other available methods the model exposes.
    tasteBugger('Check window.localStorage to see your shiny new Todo.');
    Model.save(input);
  }
};

This idea doesn't have the advantage of being easy to implement for 40+ example apps, but might be awesome.