Why Literate Programming Might Help You Write Better Code

It seems obvious, but code isn’t only written for machines: it’s written for people, too. Overlooking this fact can cause problems.

“A friend of my dad’s told me about a time he came across some truly horrible code at work. The code was terrible: poorly written, badly commented,” Joël Franusic , solutions engineer at Okta, told The New Stack via email. The man was “so incensed that he decided to figure out who wrote the code so he could give that person a piece of his mind.”

Annoying, yes. But to cap it off: turned out it was his code.

This situation neatly encapsulates a common but painful experience for developers: making sense of someone else’s work (whether that someone is past you or an actual other person). While there are a few different ways of tackling these issues, there’s one that is particularly powerful, if often overlooked: literate programming . What Is Literate Programming?

Literate programming is an approach to programming in which the code is explained using natural language alongside the source code. This is distinct from related practices such as documentation or code comments; there, the code is primary, with commentary and explanation being secondary. In literate programming, however, explanation has equal billing with the code itself.

“Documentation is fundamentally disconnected from the code,” Franusic noted. Often, “documentation is written by someone who doesn’t work on the code. This distance between code and documentation makes it harder to really understand what the code is doing.”

This underlines what makes literate programming particularly valuable: it’s a means of gaining greater transparency or clarity over code.

Having been developed in the early ‘80s by Donald Knuth , a computer scientist now professor emeritus at Stanford University, it would be easy to dismiss literate programming as a relic of a much earlier era of computing.

However, its emergence should act as a reminder that the challenges facing those pioneers of modern software engineering aren’t actually that different to today: everyone, after all, wants to write clean, clear code that people can understand and interact with at a later stage.

The fact that literate programming maintains an audience in a number of communities — such as statistics — is a clear indicator that it still has value. The only question is, are there other benefits engineers are missing out on? The Evolution of a New Approach

Before getting to that, it’s worth looking at the world in which literate programming emerged. In the years after it was first introduced by Knuth , it attracted a small but committed community of engineers and computer scientists.

Norman Ramsey , a professor of computer science at Tufts University, told The New Stack how he found literate programming when he served as technical lead for a group of engineers who worked for a U.S. government contractor.

“We were contracted to the Air Force to deliver some verification software, and the mathematics behind what we were delivering was quite sophisticated,” he said. “ And even at the time, the standard for writing mathematics down […]

Full article on original website: thenewstack.io