Discussion on: Thoughts after 6 months of literate programming

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));
expect(task.isExpired()).to.equal(true);

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

var task = new Task("text", new Date(new Date().getTime() + 1000));
expect(task.isExpired()).to.equal(false);

END

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.