Recommendations on structuring our code in notebooks?

I notice in many notebooks by @mbostock and many others, that the charts are drawn at the top while the variables and functions used to create it are defined at the bottom. The purpose of this seems to be to keep the focus on the simulation/visualization rather than the code used to generate it. But it does make it hard to understand the code if the reader’s interest is to better understand how the chart/simulation was generated.

I love this project but I would like to know if new users (programmers) who come here for understanding the code (used to generate visualizations) have a hard time understanding the code primarily due to it’s structure.

Are there any particular recommendations for structuring the code or does it all depend on the use case? If I am writing a tutorial for a viz, it makes sense to define and explain my variables at the top and gradually build the visualization. But if the sole purpose is to create an interactive essay to teach a concept then variables can hide away at the bottom with visualization and it’s explanation at the top.

Thanks for your thoughts.

1 Like

Hi @rdbcasillas,

Speaking only for myself here:

Observable notebooks aren’t intended to make the JavaScript source code easily understandable as it would need to be written in a normal script. They’re intended to make the source code easier to write and understand in and of itself — and the core component of that simplification is the fact that the cells have no defined order in which they’re going to evaluate: a cell computes when its inputs have changed.

Now, if you happen to write your normal JavaScript as a series of independent functions, each of which is passed the state it needs to compute, you’ll end up with much the same structure. But that’s not really the way that JavaScript is most often written.

You ask about recommendations for structuring the code. Since there’s no semantic difference to the ordering of Observable cells, it all depends on the use case.

If you’re showing off a graphic, and the code is the details, putting it at the bottom — or even in an Appendix — is quite nice.

On the other hand, if you’re writing a tutorial, building up your visualization piece by piece, with Markdown paragraphs interspersed to explain what you’re doing, is a lovely way to go.

Finally, your question points at the need for us to write more introductory notebooks in other styles, and from other points of view: “I’m coming from <script> tags. What’s going on here?”. “I’m used to Jupyter notebooks. What is this thing?”



Yeah, that’s what i thought was the implied reasoning in structuring the code in the way it’s structured here for most visualizations.

This is all I needed to hear! I feel a lot of us are coming from that background which brings in some confusion. If you dig enough here, it’s clear that this is potentially more useful and fun than Jupyter notebooks but seeing that quickly isn’t easy and superficially it can look more complex than in actuality.

Thanks for working on this!