DEV Community


Discussion on: Thoughts after 6 months of literate programming

jf profile image
Joël Sepulveda Franusic Author • Edited

I'll be the first to agree that literate programming has its faults. As the "literate" in the name implies, I think that the practice is best used when writing something to "publish" - I do most of my literate programming for blog posts or documentation. The tooling and toolchain has improved, I think, with Org-Babel - I tried to use web/cweb briefly, but couldn't get them working. Debugging hasn't been an issue so much. What I've found to be difficult however is refactoring. When writing a literate document, I've always started with the standard toolchain and setup. I only start writing the literate document after I have code that I'm happy with, breaking apart the code into an Org-Babel file so I can describe it.

inf3rno profile image
Jánszky László Lajos • Edited

I would try it in combination with BDD. They appear to have similar goals. If you generate user manual from it, then the tests can be examples if you design them carefully. It's just an idea though.

I would do something like this if I'd want to include the code too. I am not fond of the idea of breaking code blocks with text and documenting each line. It makes the code impossible to refactor. Even in this case the "function that returns true or false when ..." might be too much implementation detail.

TODO sample:

We want to describe tasks we intend to do with the description text and the expiration date.

var Todo = function (text, expiry){
    this.text = text;
    this.expiry = expiry;

We should be able to decide if the task is beyond the deadline. In order to do that we need a function,

Todo.prototype.isExpired = function (){
    var now = new Date();
    return now > this.expiry;

which should return true when the task is beyond deadline,

var task = new Task("text", new Date(0));

and it should return false when the task is not beyond deadline.

var task = new Task("text", new Date(new Date().getTime() + 1000));


I think literate programming has it's dangers too. I prefer clean code, where the variable and function names carry the meaning, not the comments or texts. If we add texts, then we will neglect variable naming and I am afraid we will end up writing something like math, with x,y,z-s and let the text alone explain everything. On the other hand if we start to think about the proper variable names we might find out that our initial model is wrong and we need something else. Yet another twist that the text can help name the variables and functions. E.g. instead of isExpired we could write isBeyondDeadline. I use to do that sort of thinking in github issues or txt files, but you can think it through in UML or without writing a line too. It just depends on how you prefer to think. I use to write down almost everything.