The growing popularity of Jupyter Notebooks has made people realize the power and convenience of mixing executable script/code with documentation, in the inverted way from normal. Normally we have code with embedded docs/comments, but in this new approach we have documents with embedded code. Opposite way around. I like where all this is going, but I have a question:
Maybe we can make the embedded code be "format independent" or have different embedding syntax to extract the code from various forms of docs? Technically Markdown is already a special case of plain ASCII text, so that's cool. But since Emacs Org Mode (which is supported even in VSCode via a plugin) we could have a way that's compatible with Org Mode as well? Or would that be replicating existing Org Mode features too much? I'm not experienced in Org Mode other than to prove that VSCode plugin works however, so that's why I have to ask.
It seems like it would be really helpful for AI/LLMs to understand code better if it was surrounded with tons of inline documentation too right?
One "hole" I've seen in all of modern software development is that you also normally have just documentation in the code comments, but no real linking of each code method (or function or class) to various other places in external documentation.
I know we have URLs for that, but it's usually too difficult to get URLs put into code that points to specific areas in the docs, and vice versa. And if you ask a developer a question like "What's the URL for the docs for this method" you'll get a blank stare because generally that concept doesn't exist.
Comments
The growing popularity of Jupyter Notebooks has made people realize the power and convenience of mixing executable script/code with documentation, in the inverted way from normal. Normally we have code with embedded docs/comments, but in this new approach we have documents with embedded code. Opposite way around. I like where all this is going, but I have a question:
Maybe we can make the embedded code be "format independent" or have different embedding syntax to extract the code from various forms of docs? Technically Markdown is already a special case of plain ASCII text, so that's cool. But since Emacs Org Mode (which is supported even in VSCode via a plugin) we could have a way that's compatible with Org Mode as well? Or would that be replicating existing Org Mode features too much? I'm not experienced in Org Mode other than to prove that VSCode plugin works however, so that's why I have to ask.
Have you seen https://en.wikipedia.org/wiki/Literate_programming?
No I hadn't seen that. Thanks for the link.
I had to write code at university in literate style back in the early 1990s
It seems like it would be really helpful for AI/LLMs to understand code better if it was surrounded with tons of inline documentation too right?
One "hole" I've seen in all of modern software development is that you also normally have just documentation in the code comments, but no real linking of each code method (or function or class) to various other places in external documentation.
I know we have URLs for that, but it's usually too difficult to get URLs put into code that points to specific areas in the docs, and vice versa. And if you ask a developer a question like "What's the URL for the docs for this method" you'll get a blank stare because generally that concept doesn't exist.