Hacker News Reader

Comment by arocks | Hacker News Reader

Should the order of documentation be same as order of code? For e.g. if I would like to start with explaining the main function at the bottom of the code, can this support that?

If it does not it cannot be, strictly speaking, called Literate Programming: http://en.wikipedia.org/wiki/Literate_programming#Misconcept...

View on HN

Ah, that old canard ;)

Modern programming languages (and JavaScript especially so) support defining your functions, creating your classes, and wiring things together, in any order you see fit. These days, TANGLE'ing and WEAVE'ing together a source file into a new line ordering, just to make a compiler happy, is unnecessary, and more trouble than it's worth. Just do:

    ... bulk of the file goes here ...

        main = ->
          run program

Well, there's more than one way to write literature, and there's more than one way to approach literate programs. So while I agree that you can do most of what you want with a more simplified approach, I don't think that Knuth's approach was just there to escape from Pascal's declaration syntax.

Out-of-order code can be quite useful if the literate document is the narrative of the code, how you derive your algorithms and create your functions. The final untangled code is devoid of this, and presents a more conventional structure. One example would be some global variables (or configuration hash, if that statement made you faint a bit). In the end, you probably would want at least one view of the code where this is collected in one spot, even if the programming language would theoretically allow you to declare it bit by bit all over the place.

On the other hand, this style doesn't lend itself that well to a constantly revised code base, as that would mean reading a narrative all over again.

That was exactly my line of thinking, too: Imaging you have written you literate program using all those literate-macros and TANGLE and WEAVE. If you're using a sufficiently powerful language, you can replace all your literate-macros with native language constructs.

That's why I never really felt the urge for those lterate-macros.

Moreover, I'm usually going into the opposite direction, writing LP programs that depend on as few tools as possible. For example, I wrote a LaTeX file that is also a valid shell script, executing the build instructions section when called from shell.

I named this experiment "Self-contained Literate Programming": http://www.profv.de/literate-programming/

Honestly, I am happy that you took a more pragmatic view of this. Whenever I try to write in literate style it never seemed as good as a naturally written documentation; never as good as Django documentation, for instance. I used to think it is because of my inability to structure my prose in a different order to my code.

Of course, most languages these days are late binding and do not enforce a strict ordering of parts of code. But I still think literate style is best suited for single-file source code documentation.

I truly look forward to reading your blogging engine created in literate style. All the very best!

By having the code in a differently ordered way, one can look at the compiled version to see how it flows; we get two views of the code instead of just one.

For example, we could use literate program flow to sketch the flow:

    if ( i<0 ) {
      "strip sign and reciprocate"
    }  else {
      "shift to make room for negatives"
    }

With function ordering, it would look similar but with dealWithNegative() kind of stuff and some sort of return value/scoping issue to think about. And that is all one gets.

But with literate program, you can actually look at the compiled code and get a different view; very helpful with scoping issues.

    if ( i<0 ) {
      i = 1/math.abs(i);
    }  else {
      i = i+1
    }

Admittedly, the compiled view should not be needed too often, but it is useful on occasion.

One also has the ability to quickly strip out long sections into their own snippets without having to worry about scope/closures/pass-in/return values/where to put the function.

You still need to declare variables before using them in an expression, though. I wish more languages would adopt the "where" syntax that Haskell and Miranda have. It lets you do things like:

  y = m*x + b
      where
      m = calculateSlope()
      b = getYIntercept()

I think this fits the literate programming style well.

Reply on news.ycombinator.com