Anyone into literate programming?

[Roman Hartmann]

Just a few days ago I had a look into the source code of my engine (actually a rewrite of the rewrite of the old one) and was trying to figure out the meaning of a few things. I didn't touch this stuff for quite some time so it took me a few moments to figure out how some of it works.

Anyway I remembered about literate programming to create not only a binary but also a nice documentation from the same source and gave it a go (I worked with cweb). So far I didn't create more than a few test files to get an idea how it works but it seems like a great idea to me. But looking around not too many others seem to share my opinion regarding literate programming.

Anyone ever tried literate programming? And if so why didn't you stick with it?

Best regards
Roman

[jdart]

I've been in commercial software development for over 25 years, and in that time have seen nobody using this stuff.

There are CASE tools that do design to code mapping and vice-versa. Never really seen those used successfully on a big real-world project.

There was also a big push at one time towards 4GL languages (http://en.wikipedia.org/wiki/Fourth-gen ... g_language), which get developers away from low-level code and using higher-level constructs. That has seen some successful adoption, in specific domains.

--Jon

[mar]

I don't see how you would maintain this.
I prefer small (preferably) 1 line comments in code here and there (where appropriate).

Even though doxygen (i.e. extracting documentation from comments in code) is a bit different from this literate programming, I'm not a big fan of it either (but I would argue it's easier to maintain):

It probably makes sense for libraries (when you expect a lot of people to use them)
but I really hate when they put these half page long comments before each function/method in headers.
I prefer to see the whole picture instead of digging through ton of comments just to satisfy some automated generator.
I also never found such "documentation" really useful so in my opinion it's a waste of time:

I really love things like this:

Code: Select all

/*
 * add two numbers
 * @param x input parameter x
 * @param y input parameter y
 * @return the sum of x and y
 */
func add(x,y)
{
    return x+y;
}

[Dann Corbit]

For me, literate programming is just like writing a technical paper.

You cite where you found the algorithm in the comments.

This is much better than trying to insert the whole book into your program. When you want to understand the algorithm better (in case you get fuzzy about it some time later) then you go get the reference and turn to the proper page.

[Roman Hartmann]

That's what I figured out by looking around. Most of the literate programs that can be found are rather small and mainly of academic nature.

For certain tasks literate programming seems to be the right thing though. For example to write a technical article about chess programming cweb might be the right choice imo. It's definitely more work involved working with literate programming than just writing code that will compile. And that's probably the main reason not too many are into literate programming.

It's rather easy to write nice looking documenation without making use of literate programming (by using LaTeX with lstlisting). But as soon as the code changes some work is involved to keep the documentation up to date. That's where I see an advantage for literate programming.

For one of my rather small projects I'm going therefore to make use of cweb to figure out how easy or how hard it is to apply literate programming to an ongoing project.

Roman

[Roman Hartmann]

I agree with you that documenting the source is important. Literate programming takes that one step further so that you can give certain parts of your code more weight in your documentation. As you already pointed out it doesn't make sense to document all the obvious things.

Showing the big picture is easier when you don't have to include all the lengthy and easy to understand routines.

Roman

[Roman Hartmann]

Actually I was trying to write a technical paper and including code to explain the ideas behind when I remembered about literate programming. Years ago I had looked into literate programming before but dropped it because I couldn't really see the reason for the extra work involved. But after having written a bit of code I see that a bit different.

Anyway, I'm going to give literate programming another try.

Roman

[lucasart]

I don't see how you would maintain this.
I prefer small (preferably) 1 line comments in code here and there (where appropriate).

Even though doxygen (i.e. extracting documentation from comments in code) is a bit different from this literate programming, I'm not a big fan of it either (but I would argue it's easier to maintain):

It probably makes sense for libraries (when you expect a lot of people to use them)
but I really hate when they put these half page long comments before each function/method in headers.
I prefer to see the whole picture instead of digging through ton of comments just to satisfy some automated generator.
I also never found such "documentation" really useful so in my opinion it's a waste of time:

I really love things like this:

Code: Select all

/*
 * add two numbers
 * @param x input parameter x
 * @param y input parameter y
 * @return the sum of x and y
 */
func add(x,y)
{
    return x+y;
}

+1

[mcostalba]

I agree with you that documenting the source is important. Literate programming takes that one step further

Documenting the source is important but IMO should be done with the code itself, writing self-documenting code. Literate programming takes that ten steps backward....once you have wrote a mess, adding redundant boilerplate upon it only worsen the mess.

For me literate programming it means:

1) Properly choose the names (very dfficult!)

2) Write clean code (not easy)

[vittyvirus]

I agree with you that documenting the source is important. Literate programming takes that one step further

Documenting the source is important but IMO should be done with the code itself, writing self-documenting code. Literate programming takes that ten steps backward....once you have wrote a mess, adding redundant boilerplate upon it only worsen the mess.

For me literate programming it means:

1) Properly choose the names (very dfficult!)

2) Write clean code (not easy)

+1
Very well said…