I’ve been working on a fairly complex group project in a grad school class that uses Observable. We’re in finals period now and thinking about how to best document our code, both for our own future use and for any students that pick up where we left off in future iterations of the class.
What strategies do you use for code documentation? Do you rely on commenting within the code? Has anyone had success using any of the recently-added collaboration features for the purpose of documentation?
I’m a big fan of literate programming as a way of documenting code. Rather than embed comments in code, code is embedded in ‘comments’. Observable, and other notebook environments are natural places to do this, as text and embedded code are so easy to create.
Not only does (good) literate programming help others to read and maintain your code more easily, the act of forcing yourself to explain your code often results in you writing better code in the first place. I like to think of writing and explaining code as part of the same integrated process.
Thanks for the great answer. I had somehow never heard that term, though I’ve seen millions of examples of literate programming in action. I think this approach could work particularly well in situations like ours where the “product” is a separate website that embeds notebook cells — consequently, adding additional Markdown to the notebook doesn’t impact the functionality (although it might cause a nominally slower load time).
Fully agree. I do have a wish for Observable, though. I want to have the code and its explanation stick together, so I can move them around as a single unit. That’s why at times I put comment in the code cell itself, rather than in a markup cell above or below.
You can reorder groups of cells by selecting multiple adjacent cells and then moving them via option-up / option-down. Reordering via the minimap has also been added recently, which should make it easier to keep track of where your cells end up.