Ever since I started to work on programming languages and models, I was intrigued by the problem of developer productivity. Always looking for effective ways to write and maintain code over time. One of the core issues I constantly struggle with when writing/looking at code is its readability. I generally maintain that the readability of the code has direct impact on its quality, but I digress.

There are all sorts of methodologies and tools to increase code readability, but one of the most interesting ones I came across is the idea of Literate Programming. The idea itself isn’t very new, and was conceived first by Donald Knuth in his book about that same subject.

I don’t claim to explain the idea better than the man who invented it (and I urge the reader to visit the links above to get a better understanding), but the rough idea is to write programs in the form of human-readable text, interspersed with program code. The program code is broken into snippets that are explained by the text. The resulting document is a fully functional (=”compilable”) program, using literate programming tools. It can be executed and it provides results, often embedded in the same document itself.

Being a fan of literature as well as programming, this struck me as a wonderful idea – you get to write your thoughts about what you’re trying to do, in a human readable way, and the code is right there, and it’s executable. There’s no separate documentation or anything – you explain the calculation, along with the code that actually executes it. Often times, the resulting document also contains the result of running the code, maybe even with graphs, images, etc.

There are of course limitations to this. And while I’ve no intention to start a complete debate on the validity of this approach, I will only say that I have my doubts on how this might work for developing a complex system, with several thousands/millions lines of code and a team of developers on it. While it’s theoretically possible to write such systems, I doubt any real benefit would be realized in such a scenario.

Still, for some scenarios, I believe this is a terrific method of writing software. Specifically, when trying to explain complex calculations, and making the calculations repeatable. This is why I think this kind of tools found its sweet spot in academia, where this use case is more prevalent. See iPython notebooks (python) and knitr (for R) as examples.

This is all fun and nice, but I’m not a data scientist, and I don’t delve too often into writing reports.

But then I came across a project at work, which required me to write a small tool to make some calculations, given a set of data. Besides the usual requirements for code quality, one of the prominent requirements was for users of this tool to easily understand the underlying code – the computation leading to the end results, along with intermediate results. And this struck a chord with me.

My first idea was to use R to write the code, both for its applicability as a language to the task and the availability of the knitr package mentioned above. But this was ruled out for reasons of skill set of the intended audience, and other developers who might to base their work on this tool (and also not wanting to install R/shiny to use it).

It was at this point that it came to me that even simple and readily available tools, namely a modern web browser with its javascript engine, are a great fit for the task. After all, today’s browser renders HTML pages with Javascript code running inside it all the time. So I have a presentation language (HTML), with a programming language (Javascript) and the engine to run it, all in one everyday tool – a browser. All that was left was to make it possible to write the tool that will marry both in a way that allows for the executable code to be part of the read document.

So I came up with LiterateJS.

LiterateJS was conceived originally as a proof of concept. I now evolved it to slightly more than that, but it’s no way near a mature project.

Still, it provides a demonstration and the basic facilities to write literate programming document using standard HTML and JS. ‘Standard’ being a key idea here – I intentionally try to avoid doing too much “magic”; instead trying to strike a balance between productivity and usefulness and remaining open to other tools and standards. The examples currently in the project use standard css (bootstrap) with another library for highlighting the code (highlight.js). Resulting in a standard HTML document that can be easily rendered, edited and debugged in standard tools. In this respect this isn’t a classic literate programming tool – there’s no explicit weaving step involved. The javascript code is simply extracted and with some help “injected” into the document, while preserving its highlighting and formatting. The resulting document is standard dynamic HTML document, with the code running in it.

LiterateJS is then a small framework that allows a developer to write literate programs in Javascript and HTML, and distribute them in any way he sees fit. It has a dependency on JQuery but that’s pretty much it (to be honest, the current code, at the time of writing, also depends on bootstrap css classes, but this dependency is planned to be removed).

LiterateJS is still very early in development, and I hope to have the time to continue developing it moving forward (any helpers?). Yet, I don’t expect it to grow too much, and aim to keep it a relatively small tool, with the possibility to add separate extensions later.

I encourage you to try it out, look through the examples and the code, suggest new ideas, features and of course bug fixes. Let me know if you find it useful, and program away!