#literate programming

[aestheticneet]

we do a little trolling

Is it possible to check for pointer equality in SMLNJ (for debugging)?

Suppose we have the following toy binary tree structure: datatype Tree = Leaf | Branch of Tree * Tree fun left(Branch(l,r))= l fun right(Bra

[websitedesigningplus]

Comparing Web Programming and Web Development...

Comparing Web Programming and Web Development…

What is a Web Programmer or Web Developer?:

A Web programmer or Web developer is the person in charge of making the website do things. They create the interactivity on the site including the actions on forms, rollovers for menus, and any Ajax or other programmming on the site.

The following questions detail some of the common aspects of working as a Web developer or Web programmer…

View On WordPress

[melioratus]

Work in progress: Introducing «Literate DevOps».

[agamposts]

Once upon a time I took great care to ensure that TEX82 would be truly archival so that results obtainable today would produce the same output 50 years from now but that was manifestly foolish. Let’s face it, who is going to care one whit for what I do today after even 5 years have elapsed, let alone 50. Life is too short to re-read anything anymore in the internet age. **Nothing over 30 months old is trustworthy or interesting.**

Donald Knuth

[agamposts]

Step away from the machine. Literate programming has nothing to do with tools or style. It has very little to do with programming. One of the hard transitions to literate programming is “literate thinking”.

Tim Daly

[jackrusher]

An article about computational science in a scientific publication is not the scholarship itself, it is merely advertising of the scholarship. The actual scholarship is the complete software development environment and the complete set of instructions which generate the figures.

D. Donoho, on Reproducible Research Standards, as quoted in these slides by Tim Daly.

[jostylr]

Structure versus details

I am now very much into literate programming. I created a nodejs command line tool that compiles my version of literate programs (markdown documents with some extra bit of syntax) and am working on a browser-based IDE for literate programming.

But I am still trying hard to understand the appeal to literate programming for me. It is a huge appeal, but why?

Well, a few days ago, I got my first issue request concerning literate programming. When adding to my program, I noticed my literate program code. It was the first such code I had written. It was a little bit disorganized.

I wondered why.

And then it hit me. What literate program does is provide the ability to separate structure from details.

So, for example, a literate program could have

if (a > 0) { _"deal with positive a" } else if (a < 0) { _"deal with negative a" } else { _"error of a = 0" }

In this example, something complicated could be going on with a in each of the cases. The separation into cases is one issue. The dealing with each case is a separate matter. When reviewing a program, testing it, whatever, one question is "Are the cases being split correctly?" and another question is "Is each case being handled correctly?"

For a loop, from a structural point of view, we need to see what conditions are being tested, iterated, and used to change the path of the loop. The details is what actually is being done around each loop.

max = 100; times = 0; while ( a > 0 ) { _"compute b using a" a += b; times += 1; if (times > max) { _"report maxed out" a = 0 break; } }

Notice how this automatically lets one focus on the structure of the loop and how the flow proceeds.

One thing that jumps out at me is that one could replace the literate programming snippets with function calls. This is true. But a function used in these sections is probably unnecessary. It takes a bit of code to setup a function. One needs to import the variables, give them names, export them, and/or pass in some variables that get modified in the function. Sometimes, one has as much code to deal with the return values outside the function as in.

But I think a great feature of literate programming over this use of functions is that after compiling the program into a runnable script, the code is all in one place. Literate programming is akin to having an outline of a paper with notecards as each paragraph. The compile phase takes that info and puts it into a document that can then be read. The finished script should not only be readable by machine, but also by human (at least locally).

Literate programming was developed for coding. But I think this also could be adapted to all sorts of text documents. One could write an outline of a paper and then write each of the paragraphs. Around each of them, one could put more details and thoughts than would appear in a final paper.

Of course, flow control is often not this tidy. So one should report deviations from this clearly:

_"return false if error"

where the error should be something sufficiently complicated to warrant having the flow control embedded.

Asynchronous code with its callbacks is often a headache in JavaScript. But literate programming can control it quite well.

callServer(data, _"process return");

Then in process return, whatever needs to be put in place when called back from the server can be. Note here "_process return" will be a function and hence we could have named it and placed it elsewhere. More often than not, we need to figure out where to place this function in the scope and give it a name, etc. We can inline it, but then it becomes a mess to read. So literate program allows us to move it off scene without polluting the scope with a bunch of unneeded variables.

Often though, we need to have a callback know its environment via closures. No problem. Once I code it up, the ife command will do the job nicely:

callServer(data, _"process return | ife(sent = data, i)"

would create something like

callServer(data, function (sent, i) { return _"process return"; }(data, i))

Notice how much easier it is to understand what is going on in the original. Imagine if we actually had code in process return. It gets complicated.

This is the power of preprocessing a language to mold it to one's own conventions. Literate program does not force any of these uses, but it does allow them.

How people organize is a tough problem. Some languages such as Java seem to go for structure, others, such as Lisp, go for details. Most allow programmers to decide. But literate program gives the ultimate flexibility because it allows the programmer to organize for the human first, then the computer. It is a language agnostic way to handle structure vs. details.

The difficulty in making clear organization structures may be one reason why developers have not embraced literate programming. But I think it is a crucial problem to solve and one that experience usually solves eventually.

One thing to keep in mind is that what is structural vs. detail is contextual. As an analogy, think of a company. To upper managment, the people in lower managament are workers. To those in lower management, they are part of management, not workers.

And so it is with structure in a literate program. We can structure it at various levels and as we descend that which was a detail, becomes a structure for the next level.

[cwebbdesign]

What is Literate programming?

The literate programming paradigm, as conceived by Knuth, represents a move away from writing programs in the manner and order imposed by the computer, and instead enables programmers to develop programs in the order demanded by the logic and flow of their thoughts.

In case you've been wondering what Literate Programming is, there's a really decent article on Wikipedia about it. Literate Programming

And if you're looking for a JavaScript related example, Docco describes itself as 'written in literate CoffeeScript which gives you a couple places to start looking.