10

I have recently found the concept of literate programming. And I found it rather intriguing. Yet I have not been encountered with claims that it is a bad way to structure a program. It seems not covered many places. Not even here could I find any questions regarding this.

My question is not about its flaws or ways of handling documentation. I consider the documentation a side-effect of what it would mean for the flow of literate programming. I know that the design was originally intended for easy documentation as well as the concept of forward programming flow.

The concept of dividing the problem into small sentence based problems seems to be really a brilliant idea. It will thus ease the understanding of the program's flow.

A consequence of the literate design method is also that the number of functions required will be limited to the imagination of the programmer. Instead of defining a function for a certain task, it could be created as a scrap in the literate method. This would yield automatic insertion of the code, instead of a separate function compilation and subsequent requirement of an inter-procedural compilation optimization step to obtain the equivalent speed. In fact Donald E. Knuth first attempt showed an inferior execution time, due to this very fact. I know that compilers can be made to a lot of this, however this is not my concern.

So I would like to get feedback of why one should consider this a bad/good design methodology?

S.Lott
  • 45,264
  • 6
  • 90
  • 154
nickpapior
  • 201
  • 1
  • 5
  • 2
    Zeroth, I created the [tag:literate-programming] tag and added a summary based on the Wikipedia article. Please help expand the tag wiki with relevant information. – yannis Jan 31 '12 at 20:10
  • @YannisRizos I will add it here, I do not have edit privileges. – nickpapior Jan 31 '12 at 20:25
  • 1
    Well, me neither :) I've added some resources (the wikipedia article, and the links in your question), they will appear when the edit is peer reviewed and accepted (?!). It's an intriguing approach, and since you are already exploring it, come back and improve the tag wiki every time you find something that you think it's worth mentioning in there. – yannis Jan 31 '12 at 20:30
  • A design methodology which follows the programmers nature of the program-flow. Explain the program while programming. The program is written in `scraps` together with the documentation. A `scrap` is a code segment which has a sentence description which can be referred to by other `scrap`s. The `scraps` are collected by a `WEB` parser, creating the actual code and/or documentation. – nickpapior Jan 31 '12 at 20:31
  • 1
    I would recommend the author of the Literate Programming site to visit the UX stackexchange site - the colors are really bad for reading. – Danny Varod Jan 31 '12 at 23:03
  • 1
    FYI, there is a `literate-programming` tag on StackOverflow as well. There's more content there, although still not much. – Ross Patterson Feb 15 '13 at 11:59

4 Answers4

10

This would yield automatic insertion of the code, instead of a separate function compilation and subsequent requirement of an inter-procedural compilation optimization step to obtain the equivalent speed

This is irrelevant. Has been for decades. You can remove it from the question, since it makes no sense with modern compilers to subvert their optimizers.

So I would like to get feedback of why one should consider this a bad/good design methodology?

There is no downside to literate programming. (I expect dozens of -1 votes for that sentiment.) As a practitioner, I've never seen any problems.

There are some arguments against which all amount to "programming in a higher-level language is be subverted by tweaking the resulting code." Right. In the same way that programming in C++ is subverted by tweaking the .o file that gets produced. It's true, but irrelevant.

Writing literate programs merely means combining high-level and detailed (code-level) design into one document, written with a suitable toolset that produces compiler-friendly files and people-friendly files.

When Knuth invented literate programming, mainstream OO languages didn't exist. Therefore a great deal of the original web and weave tools allowed him to create class-like definitions for abstract data types.

Much of that is irrelevant nowadays. Literate Programming tools can be quite simple if they're focused on modern, high-level object-oriented (or functional) programming languages. There is less need for elaborate workarounds because of the limitations of C (or Pascal or Assembler).

The approach to writing literate programs is no different from the approach to writing illiterate programs. It still requires careful design, unit testing, and neat coding. The only extra work is writing explanations in addition to writing code.

For this reason only -- the need to write coherent explanations -- literate programming is difficult for some programmers. There are a fair number of programmers who are successful (their code passes all the unit tests, is neat and easy to understand) but can't seem to write a coherent sentence in their native language. Don't know why this is true.

There are a very large number of programmers who appear to be only marginally successful and then only by accident. (There are enough bad questions in Stack Overflow that indicate that many programmers struggle to even grasp the fundamentals.) For programmers who ask largely incoherent stack overflow questions, we know they can't really do a good job of literate programming, because they can't do a good job of programming.

S.Lott
  • 45,264
  • 6
  • 90
  • 154
  • 7
    A large number of programmers are barely coherent when explaining something in any medium, formal or informal, be it literate programming, writing comments or even an email. It's a wonder software works at all :) – Andres F. Jan 31 '12 at 20:47
3

The most important aspect of literate programming (or even just good commenting) for me is not so much that it provides documentation, but rather it states the intent of the programmer. In knowing the stated intent, you can immediately judge whether or not the code following it really does what it should. Without intent, you have to begin with the assumption that the code is correct and then prove it right or wrong by induction -- which is more exhausting and time consuming as it often requires becoming familiar with all the surrounding code as well.

So stated intent often enables others unfamiliar with the code to quickly jump in and find errors it without having to know the larger context surrounding it.

And of course, it helps you to learn the basic flow and design of the code faster as well, as plain English is often more intuitive than pointer arithmetic for most people.

Mike Owens
  • 339
  • 1
  • 7
1

While rather new to the concept of litterate programming myself (and it's therefore likely that I'm missing the boat entirely), it seems very much to line up with the concept of a DSL.

The idea behind a DSL is to distill down a domain of problems into a simple, natural-language-oriented grammar that can be used to built algorithms for solving those problems.

To me, that same idea, or at least the core foundation of it, is the same or at least closely related to literate programming.

In the groovy world, for example, there is a strong push to use DSLs more regularly and to create new DSLs to solve common problems. This push comes from both tools within the language (easy builders), as well as core libraries supporting a DSL-based API.

Given that the trend, at least in that corner of the world, is towards literate programming, I would say that it is a good methodology to strive for.

Unfortunately, the level of thinking needed to create a good dsl is often beyond most programmers, from what I've seen. I know I personally struggle with some of the concepts needed from time to time. It may be this difficulty that has prevented such techniques from gaining more wide-spread adoption.

It's your classic case of when using the tool is one thing, but creating it is on a whole different level.

To expand on my point of view a bit, it isn't s much that DSLs are the same thing as literate programming, but rather that they make literate programming much more possible. Particularly when they are natural language DSLs.

In version 1.8 of groovy, the natural language DSL capability was substantially improved with the addition of more powerful command chains.

For example, the following lines of code are programming, not just pseudo-sentences:

drink tea with sugar and milk
move left by 30.centimeters
sendFrom "Guillaume" to "Jochen"
send from: "Jochen" to "Lidia"
Email.from "Lidia" to "Guillaume" withBody "how are you?"
contact.name "Guillaume" age 33
move left by 30.centimeters
sell 100.shares of MSFT
take 2.pills of chloroquinine in 6.hours
blend red, green of acrylic
artist.paint "wall" with "Red", "Green", and: "Blue" at 3.pm
wait 2.seconds and execute { assert true }
concat arr[0] with arr[1] and arr[2]
developped with: "Groovy" version "1.8-beta-2"

Note: Code sample comes from Guillaume Laforge's blog

The core idea behind literate programming is that natural language is more understandable for humans and that is what matters. Groovy's natural language DSL capabilities make that a much closer reality, in my opinion. Especially when those DSLs are used to create business rules for an application.

Being able to "encode" the critical components of a system using natural language is the very essence of literate programming. Having to intersperse natural language with chunks of code is a bastardized form of literate programming. While useful, I believe that natural language DSLs that allow you to use natural language as the code itself are a huge leap forward.

Expanding the capability to programming in general is the next step in the process, but to a large extent the tools to do so are already in place. Yes, there is not a "general" DSL yet, but for smaller domains, the capability is there.

For more examples of this in action (in no particular order):

Community
  • 1
cdeszaq
  • 322
  • 1
  • 13
  • 2
    Interesting point of view. From my perspective it doesn't line up very well at all with a DSL. Since the literate programming is **in** some non-DSL language. And the tools are not much like a DSL, either. They aren't oriented toward the problem domain. Could you provide an example of how you think literate programming is like a DSL? A link or a reference to an example might help clarify your answer. – S.Lott Jan 31 '12 at 21:45
  • One example of this is the command chains in Groovy 1.8 that let you "program" with things like `turn left then right` or `paint wall with red, green and yellow`: http://docs.codehaus.org/display/GROOVY/Groovy+1.8+release+notes#Groovy18releasenotes-CommandchainsfornicerDomain-SpecificLanguages – cdeszaq Jan 31 '12 at 22:01
  • @S.Lott - I agree that there is definitely a difference between DSLs and literate programming, but I think DSLs may be a _tool_ for achieving _true_ literate programming where you can type natural-ish language and have it express the desired algorithm. To me, mixing natural language and code is a bastardized form of literacy. – cdeszaq Jan 31 '12 at 22:04
  • "you can type natural-ish language and have it express the desired algorithm" is unlikely at best. There's background, justification, correctness proof, complexity assertions (big-**O**) and lots of non-alogrithmic supporting documentation that's not part of a DSL scheme. I'm not sure I agree with the parallel now that you've clarified it. – S.Lott Jan 31 '12 at 22:15
  • @S.Lott Based on the wikipedia article, I believe that natural-language DSLs in Groovy _are_ literate programming: "A literate program is an explanation of the program logic in a natural language, such as English, interspersed with snippets of macros and traditional source code..." – cdeszaq Jan 31 '12 at 22:32
  • 1
    "explanation of the program logic". Not the logic itself. But an explanation. The logic is rarely self-explanatory. It never contains a proof of correctness (that's difficult and sometimes impossible). It rarely contains a justification of the big-O complexity. And it rarely explains the alternatives which are either lower performance or more memory. So, I would suggest that DSL falls well short of "explanation". – S.Lott Feb 01 '12 at 01:53
-2

I think this is mistake to think that LP is some kind of DSL. Because LP is -- journal (with diagrams, schemes, pseudo-code fragments, i.e. chunks) of developed program, it's architecture and so on... It's absolutely analogue of paper notebook - many of developers use they but after finishing of program - drop out your' notebooks, papers...

Long time ago each physicist, astonomer, chemist/alchemist, mathematician has own notebooks, manuscripts with many schemes, needful information, tables, and without them you can understand or repeat their successful experience, his results. And always between such peoples exists manuscreepts/notebooks hunting.

Today many programmers writes code, and sometimes they adds comments! Byt program is not only code - it's thoughts, ideas, imagination, concepts and when new developer inherits alien code - he brokes all ideas and concepts often, makes different "loopholes" and "backdoors", I hope you understand me :)

So, main requirement for LP (as tool!) is too allow all of these with simple, light, readable syntax. I tried many LP tools, but today i'm developing own - NanoLP (http://code.google.com/p/nano-lp/) which is aims to acomplish this demand.

RandomB
  • 101
  • 1