Slashdot Mirror

> No, I would say that pure C is completely free from landmines.

Oh, it has plenty but remember that C was designed for experienced programmers, not for beginners.

Kind of reminds me of the Hole Hawg versus your typical consumer power drill.

``Pascal as defined was not suitable for large projects...''

Unless of course, one is Dr. Donald Knuth, then one creates a brand new programming paradigm: http://www.literateprogramming...

and writes programs such as TeX: http://www.ctan.org/tex-archiv...

Somewhere, I have a copy of the Oberon language manual printed out --- it's quite cool, and very concise.

Why doesn't Literate Programming ever make these lists?

http://www.literateprogramming.com/

Sad that fewer people own /read Literate Programming (Center for the Study of Language and Information - Lecture Notes) by Donald E. Knuth (Jun 1, 1992) than TAOCP.

Dr. Donald Knuth has opined that Literate Programming is the most important computer science concept which he has created and that TeX and Metafont couldn't've been written w/o that technique:

http://www.literateprogramming.com/

I've found that using it for the TeX projects I do results in much more maintainable code which was also easier to write initially.

Knuth's source for TeX and METAFONT does this (he created the technique to enable him to write the system).

I've found (re)writing a program as a literate program results in a much cleaner representation of the code and algorithms and a clearer, more understandable manual.

DEK has since written an entire book on the concept (_Literate Programming_ a CLSI series book) a decade ago, but one seldom sees source so provided.

There are some really cool example programs which're quite interesting (and educational) to read, for example:

Will Crowther's game Adventure - available here: http://sunburn.stanford.edu/~knuth/programs/advent .w.gz (with an offer of a $2.56 reward check if one can find a bug), or as a document to just read here: http://www.literateprogramming.com/adventure.pdf

Or a CWEB version of the RPN calculator for K&R's C Book: http://www.literateprogramming.com/krcwsamp.pdf

Knuth's source for TeX and METAFONT does this (he created the technique to enable him to write the system).

I've found (re)writing a program as a literate program results in a much cleaner representation of the code and algorithms and a clearer, more understandable manual.

DEK has since written an entire book on the concept (_Literate Programming_ a CLSI series book) a decade ago, but one seldom sees source so provided.

There are some really cool example programs which're quite interesting (and educational) to read, for example:

Will Crowther's game Adventure - available here: http://sunburn.stanford.edu/~knuth/programs/advent .w.gz (with an offer of a $2.56 reward check if one can find a bug), or as a document to just read here: http://www.literateprogramming.com/adventure.pdf

Or a CWEB version of the RPN calculator for K&R's C Book: http://www.literateprogramming.com/krcwsamp.pdf

::applause::

Some useful links for those who aren't familiar w/ it:

http://www.literateprogramming.com/

http://en.literateprograms.org/LiteratePrograms:Welcome

and best of all, Crowther's Colossal Cave Adventure as a literate programming novel translated by Donald Ervin Knuth:

http://www.literateprogramming.com/adventure.pdf

I've found literate programming to be invaluable for coding up infrequently touched systems which need updates from time-to-time.

William

::applause::

Some useful links for those who aren't familiar w/ it:

http://www.literateprogramming.com/

http://en.literateprograms.org/LiteratePrograms:Welcome

and best of all, Crowther's Colossal Cave Adventure as a literate programming novel translated by Donald Ervin Knuth:

http://www.literateprogramming.com/adventure.pdf

I've found literate programming to be invaluable for coding up infrequently touched systems which need updates from time-to-time.

William

Send your programmers this link:

http://www.literateprogramming.com/

and have them read this book:

http://www.amazon.com/Literate-Programming-Center-Language-Information/dp/0937073806/ref=sr_1_1?ie=UTF8&qid=1326462347&sr=8-1

``Propaganda'' here:

http://vasc.ri.cmu.edu/old_help/Programming/Literate/literate.html

I re-wrote the typesetting back-end of an interactive, graphical ad design / generation program as a literate program and it made a _huge_ difference in the maintainability of the system and made adding additional features _much_ easier.

The program source code type which I've learned the most from has been those which are written in the ``Literate Programming'' style developed by Dr. Donald Knuth to write TeX ( http://www.literateprogramming.com/ ).

The only program I'm aware of written as a Literate Program in C++ and publicly available is the Ynot logic simulator:

http://www.brpreiss.com/books/opus3/

William

True about visual programming, but I've always found it a great shame that Web never took off. You write your code as a story and then the compiler separates your explanation into documentation and the code into a compiled program. Way ahead of its time. One of Donald Knuth's ideas. See http://www.literateprogramming.com/ for more information.

Heh - comparing waterbear to literate programming is sort of like comparing a donald duck comic with War and Peace, come to think of it :)

Easy, use literate programming techniques ( http://www.literateprogramming.com/ ) and then typeset them using standard TeX semantics:

a) a hyphen == ``-''
b) a dash == em-dash ``---'', en-dash ``--''
c) a minus sign == $-$ or \[-\] or \{-\} or \begin{equation}-\end{equation}

More importantly, this allows one to use the full expressability of TeX to show the algorithms which are underlying the relevant code.

William

Sounds sorta like literate programming.

To my mind, the best coding standard is Don Knuth's Literate Programming: http://www.literateprogramming.com/. Quoting:

I believe that the time is ripe for significantly better documentation of programs, and that we can best achieve this by considering programs to be works of literature. Hence, my title: "Literate Programming."

Let us change our traditional attitude to the construction of programs: Instead of imagining that our main task is to instruct a computer what to do, let us concentrate rather on explaining to human beings what we want a computer to do.

The practitioner of literate programming can be regarded as an essayist, whose main concern is with exposition and excellence of style. Such an author, with thesaurus in hand, chooses the names of variables carefully and explains what each variable means. He or she strives for a program that is comprehensible because its concepts have been introduced in an order that is best for human understanding, using a mixture of formal and informal methods that reinforce each other.

There's a terrible irony in Donald Knuth feeling that it's an even more important development than TeX, yet outside of the TeX world, almost no one uses it:

http://www.literateprogramming.com/

William

I agree totally about the need for verbosity. I'm a fan of Donald Knuth in this regard.

That has nothing to do with literate programming. That Wikipedia article is very poorly written.

You can find an example of the old classic ADVENTURE game, ported to C, here, in the file adventure.zip.

Run that through the appropriate tools, and you end up with code to feed the compiler, and a listing to give humans. The listing for humans is here.

That has nothing to do with literate programming. That Wikipedia article is very poorly written.

You can find an example of the old classic ADVENTURE game, ported to C, here, in the file adventure.zip.

Run that through the appropriate tools, and you end up with code to feed the compiler, and a listing to give humans. The listing for humans is here.

According to Wikipedia, a modified version of lcc was used for compiling Quake III. It seems to me, this compiler would be far more maintainable, but for some reason, the world doesn't seem ready for literate programming.

This is why the grandmaster of 'Literate Programming', Donald Knuth, has done a translation into his CWEB Language which is totaly devoid of jumps and other 'dirty' Fortan:
http://www.literateprogramming.com/adventure.pdf

"Right now I can't remember the last time I saw a "best viewed in IE X.0" "

Yeah, and that's a good thing too. But some sites are still made for IE6 even though they don't say it. Here is a site That does not say IE6 on it but it has some rendering issues on every browser I tested except IE. Ironically, the DOCTYPE is XHTML 1.1 with CSS which is something IE6 isn't good at.

I even sent them a simple fix to their CSS so it would render correctly for modern browsers and IE6 but they did not implement it.

Computer code is not prose.

I'm not advocating this particular methodology, but there are people who would disagree with you.

http://www.literateprogramming.com/

Literate programming

Knuth's celebrated essay Literate Programming is available here. Also, Knuth has written an entire book on this subject whose complete text is available here.

Before all else, learn Literature Programming, in the style invented by Don Knuth.

We use nuweb---it works with any language.

Then I went back and read it and found that document does reference pen and paper and it also says "All these thoughts and ideas have one common goal: Reduce the users effort while creating a document. The user should only enter the data e.g. the text and define a layout and a structure. He should concentrate on the things that matter."

Perhaps someone should implement this. Someone might even write a GUI frontend to it!

Long before Trac for Subversion, there was CVSTrac for CVS. It's a little more austere, but offers the same features: integrated wiki, CVS change tracker, CVS browser, and trouble tickets. CVSTrac now can be compiled to support Subversion.

FitNesse combines a Wiki with an acceptance testing tool. Tables on Wiki pages hold test data and expected outputs; click the "test" button and FitNesse runs your application with the test data and checks the results against the expected values (similar to JUnit and others). Although written in Java, FitNesse also can test Python, Ruby, C++, .NET, Smalltalk, and Perl applications. FitNesse builds on Fit, the Framework for Integrated Testing by Ward Cunningham, the creator of the original Wiki.

Ward also was the first person to integrate source code into a Wiki. In his WikiBase , Ward presents the source code for his original Wiki on Wiki pages containing HyperPerl, a Perl implementation of Literate Programming. This may not suit current development needs, but it is fascinating.

I'm sure a book called C Puzzlers would sell at least twice as well as this.

Would you settle for slightly different titles like these?
C Traps and Pitfalls
Enough Rope to Shoot Yourself in the Foot

Fortunately, there's also:
The C Answer Book
Which obviously has all the answers. :-)

Actually, none of these is settling at all -- all three are excellent books, at least IMO. Much of Holub's book also applies about as well to Java as to C or C++, for that matter.

--
The universe is a figment of its own imagination.

    http://www.literateprogramming.com/

Overall, this fella's article is just stupid. He gives very good examples of bad comments, and then goes on to give some "good" examples, which are just as poor:

      var teamCount; // loop counter

which is it? the count of the number of teams you have, or a loop counter? if it is a loop counter, why not just label it i? Overall this article was useless at best, and down right wrong at worst.

I would say their is an art to programming. And that good programming is as much art as it is science. But it's a lot like asking if mathematics is art? We do have things like Perl Poetry and Literate Programming.

Other than that I think this is yet another stupid question.

Well if humor is art then this old Unix sex joke is art: # unzip ; strip ; touch ; finger ; mount ; fsck ; more ; yes ; umount ; sleep

In "Literate Programming" the comments are all important and the code itself is trivialized. The code, as Jef told me, is like "raisons in the muffin of the comments." There are paragraphs of verbiage which might go on about the history of the project, why certain features were discarded, etc., etc, and might not even explain what the following line or two of code was concerned with.

It's really very difficult to deal with code that has been written in this style ("literatized?" ) since the actual structure of the program is severly obscured. It serves as an example of how overdoing a good thing is usually a bad thing.

Jef was a nice guy, and I recommend his book, "The Humane Interface" for its many interesting ideas. His attempt to put them into practice in the Archy project http://rchi.raskincenter.org/aboutrchi/index.php/, was not completed before his death. Even for that, Archy is very close to his vision.

But since Jef was in many ways an extremist, one can demonstrate in Archy his pushing of his concepts to the limit resulted in the end fully maching his goals. Somewhat like "Literate Programming", in fact.

It sounds like yet another reinventing of Literate Programming and The CWEB System of Structured Documentation by Donald E. Knuth. See also: www.literateprogramming.com. Some quotes:

"I believe that the time is ripe for significantly better documentation of programs, and that we can best achieve this by considering programs to be works of literature. Hence, my title: "Literate Programming."

"Let us change our traditional attitude to the construction of programs: Instead of imagining that our main task is to instruct a computer what to do, let us concentrate rather on explaining to human beings what we want a computer to do.

"The practitioner of literate programming can be regarded as an essayist, whose main concern is with exposition and excellence of style. Such an author, with thesaurus in hand, chooses the names of variables carefully and explains what each variable means. He or she strives for a program that is comprehensible because its concepts have been introduced in an order that is best for human understanding, using a mixture of formal and informal methods that reinforce each other." -- Donald Knuth. "Literate Programming (1984)" in Literate Programming. CSLI, 1992, pg. 99.

More quotes:

"The philosophy behind CWEB is that an experienced system programmer, who wants to provide the best possible documentation of his or her software products, needs two things simultaneously: a language like TeX for formatting, and a language like C for programming. Neither type of language can provide the best documentation by itself; but when both are appropriately combined, we obtain a system that is much more useful than either language separately.

"The structure of a software program may be thought of as a "WEB" that is made up of many interconnected pieces. To document such a program we want to explain each individual part of the web and how it relates to its neighbors. The typographic tools provided by TeX give us an opportunity to explain the local structure of each part by making that structure visible, and the programming tools provided by languages like C make it possible for us to specify the algorithms formally and unambiguously. By combining the two, we can develop a style of programming that maximizes our ability to perceive the structure of a complex piece of software, and at the same time the documented programs can be mechanically translated into a working software system that matches the documentation.

"Besides providing a documentation tool, CWEB enhances the C language by providing the ability to permute pieces of the program text, so that a large system can be understood entirely in terms of small sections and their local interrelationships. The CTANGLE program is so named because it takes a given web and moves the sections from their web structure into the order required by C; the advantage of programming in CWEB is that the algorithms can be expressed in "untangled" form, with each section explained separately. The CWEAVE program is so named because it takes a given web and intertwines the TeX and C portions contained in each section, then it knits the whole fabric into a structured document." -- Donald Knuth. The CWEB System of Structure Documentation. Addison-Wesley. 1994. pg. 1.

In other words, paraphrasing Henry Spencer, "Those who do not understand the ideas of Donald Knuth are condemned to reinvent them, poorly."

If you like this approach, you might want to take a look at Knuth's "Literate Programming." One place to start is http://www.literateprogramming.com/

In either case, one needs to remember that too much can be as bad (or worse!) than too little. In real life, you may not always be the one to edit the code, and if someone edits the code but doesn't update the commentary, you can get into real trouble.

-Hil

Thanks for replying (even though my non-troll post was modded troll by the crackheads here--which I knew would happen and hence the anonymous posting.).

I don't disagree with most of what you say. Of course its critical to know the foundations of the field, to read The Art of Computer Programming, etc. Not a moment of disagreement from me about that. I see nothing incompatible with that belief and my posting, however--don't read more into my point than I said.

Speaking of Knuth, recall that one of Knuth's great innovations was literate programming, a way of writing programs in a way that they could be easily read and understood by humans. I believe that the fundamental insight there--that there is value to reading other peoples' code--carries over to include reading non-literate programs as well.

There's value in reading really good code written by really sharp people.

Indeed. And unless you've worked at MS and seen their code already, I still think it's closed-minded to dismiss the value of their code out of hand.

How do they even know if they haven't acquired the basic knowledge to tell the difference between code that's worth reading and code you know you can toss into dev/null after reading the first few lines?

Call me crazy, but I think a great way to learn the difference between good code and bad code is to read other peoples' code. Just like reading literature, poetry, whatever, eventually one builds up an aesthetic. And the point is that the only way to build that aesthetic (IMHO) is to read code in the first place. And that aesthetic is what one needs to write good code ones self.

"checking for stdlib.h..." indeed. If you don't have an ISO-C environment, you're so screwed that there's nothing autoconf can do to save you: you don't know how the language works, so whether or not you're missing a few library functions isn't going to make any difference.

I once worked on a fairly large process control system, of which less than 1% was portability code. It ran on Solaris, AIX, HP-UX (this was pre-Linux). It also ran on VMS and WinNT. Most of the portability issues dealt with the entirely different models for process management and memory-mapped files, not with pipsqueek stuff like autoconf.

It's real simple: you read the docs. You determine what the standard actually requires, not what your development system happens to do. And you program to that, then test.

As for the autotools proclaimed ability to port to systems you weren't planning for, that's so much BS. If the system is sufficiently different that ANSI C and POSIX aren't sufficient, then you're going to have to update your code anyway.

Replacing autoconf with some other crutch isn't going to help. Just ditch it entirely.

Consider totally flat c-code, that is long enough that it's not immediately visible - you have absolutely NO IDEA about what block is what if the starting {:s are outside of your view, whereas with whitespace blocks are still clearly separate.

The nice thing about using a fixed block delimeter as opposed to white space, imho, is that it doesn't add "context" to the idea of what's important to a reader, versus what's important to a compiler. Further, it can bring you closer to the model of generating human and machine output from the same document (which has some merit and proponents).

Also, if you have a flat c file, just run indent. Because the blocking is context independent, you can apply any style to the code that makes it easy for you to read.

Unless you print out the source code, bind it together, and read it in bed before going to sleep... I don't think that applies.

sph

I think the legal world needs Literate Programming, then. LAWWEB, anyone?

But a simple look at any bugtrack should back me up. Most errors are due to memory leakage, buffer overflows and other artifacts of C programming.

Bugtrack will almost certainly tell you that buffer overflows are a large source of security bugs but this doesn't back you up at all, as there are a lot of good C string APIs and using one that stops buffer overflows is trivial.

Literate programming means writing well in code. It means much more then comments and I urge you to some research into it.

I'm well aware of what literate programing is, and it is little more than writing everything twice. It makes the actual code very hard to read IMO, due to copious amounts of "coments".

While you could argue that TeX is "perfect", the debian network interface code is much less useful than the Red Hat version and changing it was much harder.

In that case then open source programs will continue to suffer from too many bugs.

In your opinion, in my opinion having the people who implement the code design the code makes for a much better result.

I believe that programs should read like novels; there should be long paragraphs of text that describe what and how the code is working followed by short bursts of actual 'dialog' that is the actual source instruction to the computer.

Donald Knuth came up with a system like this in the late 70s, calling it "Literate Programming". Aside from him, I have never actually seen it used by anybody.

The above posting is misinformed.

Check out the Literate Programming website cited in the original article for a look at what how Knuth and others define Literate Programming.

I'm not much myself on the idea of font changes and such in an XML-commented source file, but programming itself is much more than "communicating instructions to the computer." This is especially important in the eyes of literate programmers, who emphasize the fact that programs are primarily meant to be read by fellow human beings and secondarily by computers.

A lot of the articles on literateprogramming.com can expand on this theme.

Communicating instructions to the computer is easy enough. Lights, switches, and papertape can do that well. Communicating a complex process to people is difficult. Object-orientation and literate programming can help that process.

When a programmer is simultaniously coding and documenting thier code, at both the high and low levels, the larger "thought" bugs will decrease in number and severity.

Even if you don't use a literate programming system, often documenting the system before you write it can help make the code more clear.

- Serge Wroclawski

... is the only truly well-commented code. Literate programming was invented by Knuth. If you don't know who Knuth is: he's the author of the definitive CS work called "The Art of Computer Programming". Ask any of your friends who actually studied computer science about it.

Knuth wrote more than books. For example, he wrote the typesetting program, TeX which is to this very day the most popular way academics in the CS field employ to write their papers (especially using a macro package called LaTex). He just wasn't satisfied with the available ways to write mathematical books at the time (early 80s). He had a good reason - you can see the difference in quality between it and anything else - especially Word (Ugh).

To ensure you'll have the right idea about the quality of his work, note he's actually sending people checks when they find a bug in his books or his code. Of course people tend to frame them rather than cache them :-). Also note that nobody has managed to obtain such a check for a long time.

So, what is literate programming anyway? Instead of inventing yet another definition, here's a pretty good definition which you can find in the site, together with many others:

Marc van Leeuwen. "Requirements for Literate Programming" in CWEBx Manual, pg. 3-4.

The basic idea of literate programming is to take a fundamentally different starting point for the presentation of programs to human readers, without any direct effect on the program as seen by the computer. Rather than to present the program in the form in which it will be compiled (or executed), and to intercalate comments to help humans understand what is going on (and which the compiler will kindly ignore), the presentation focuses on explaining to humans the design and construction of the program, while pieces of actual program code are inserted to make the description precise and to tell the computer what it should do. The program description should describe parts of the algorithm as they occur in the design process, rather than in the completed program text. For reasons of maintainability it is essential however that the program description defines the actual program text; if this were defined in a separate source document, then inconsistencies would be almost impossible to prevent. If programs are written in a way that concentrates on explaining their design to human readers, then they can be considered as works of (technical) literature; it is for this reason that Knuth has named this style of software construction and description "literate programming".

Does it work in practice? All I can say is that I have used it in a real-world project with great success. The main downsides to it, and this applies to any type of documentation, is that it takes up-front time (even if it does save time later), and that you need to employ people with some measure of writing ability. It is surprising how many people can code well, but are hard-pressed to write coherent, readable description of their code. Especially if you write your documentation in English and the programmer's native language is Hebrew or Russian :-(

Oh, and it also is hard to do in IDEs like Visual Studio. And you won't learn about it in your university, never mind your VB in 3 days course. Just like design by contract and many other techniques, the problem isn't that humanity doesn't know how to write software well - it is that humanity doesn't want to.

The practitioner of literate programming can be regarded as an essayist, whose main concern is with exposition and excellence of style. Such an author, with thesaurus in hand, chooses the names of variables carefully and explains what each variable means. He or she strives for a program that is comprehensible because its concepts have been introduced in an order that is best for human understanding, using a mixture of formal and informal methods that reinforce each other. Donald Knuth. "Literate Programming (1984)" in Literate Programming. CSLI, 1992, pg. 99.

• Literate Programing: What you write, should make sence. Variables such as a, b, c, thing, object, stuff, crap etc should not be allowed. A new programmer should be able to come into your shop, read the code and it should make sense.

Maybe you mean something different here, but Literate Programming is a field, invented by Donald Knuth, that has little to do with what you are saying here.

There are many good reference, try this one, for example.

AFAICT, the tradition of Literate Programming comes out of Mathematics where proofs are given as narrative, but the equations (programs by analogy) are terse.

For example, this example, written by Knuth himself, contains many example of terse variable names like rx, h, t, l, etc.

• Literate Programing: What you write, should make sence. Variables such as a, b, c, thing, object, stuff, crap etc should not be allowed. A new programmer should be able to come into your shop, read the code and it should make sense.

Maybe you mean something different here, but Literate Programming is a field, invented by Donald Knuth, that has little to do with what you are saying here.

There are many good reference, try this one, for example.

AFAICT, the tradition of Literate Programming comes out of Mathematics where proofs are given as narrative, but the equations (programs by analogy) are terse.

For example, this example, written by Knuth himself, contains many example of terse variable names like rx, h, t, l, etc.

I wish Windows did the job well. For all my preaching, the application I currently work on has pieces that run in Solaris on a Sun UE10K, OS/390 on an IBM mainframe, OpenVMS on a DEC Alpha, and various pitiful, troublesome versions of Windows (file serving and the client GUI).

Our development work is done on Windows because, yep, it came with the PCs we bought from Dell. Our company is taking a real hard look at Linux for the desktop, though. MS wants to switch our licensing and have us pay them an additional 20-some million dollars in additional fees. We politely said "No."

...the telephone system was just so wonderful and cheap when a single, large monopoly ran it, right?

The monopoly was bad, but deregulation is proving to be a bigger disaster. Any extreme is bad, including extreme capitalism or the lack thereof. Why do you think Mr. Greenspan recommends normalizing influences in the form of interest rate adjustments?

...there are some inefficiencies associated with that, but nothing compared to the inefficiencies of having a single, centrally planned operating system everywhere...

Isn't Linux a centrally planned OS (Linus)? Maybe we clone Mr. Knuth and have him manage that fictional OS (everybody would use because it'd be that good). Your choice of languages would be MMIX, C, C++ and Java (those supported by CWEB ). Who said anything about a crushing bureaucracy planning the OS? I think a form of community process, similar to the one Java goes through, would actually be a good thing. I think a centrally planned OS doesn't necessarily go hand in hand with a monopoly. I lean more toward Neal Stephenson's point of view, that OSes probably shouldn't be products. (Please note that I'd distinguish a distribution, with bells and whistles, as distinct from the core OS; the kernel, and standard IO services)

C-x C-c

And, yes, I know that a flame could argue that many other commercially sold Microsoft products could be called "unsupported tools," so let's try to steer any jokes onto a different track...

Leo is a programmer's editor that represents a noweb or CWEB (literate) program as an outline. The combination of literate programming and outlining creates a powerful and enjoyable new way of programming.

Donald Knuth. "Literate Programming (1984)" in Literate Programming. CSLI, 1992, pg. 99.
I believe that the time is ripe for significantly better documentation of programs, and that we can best achieve this by considering programs to be works of literature. Hence, my title: "Literate Programming." Let us change our traditional attitude to the construction of programs: Instead of imagining that our main task is to instruct a computer what to do, let us concentrate rather on explaining to human beings what we want a computer to do. The practitioner of literate programming can be regarded as an essayist, whose main concern is with exposition and excellence of style. Such an author, with thesaurus in hand, chooses the names of variables carefully and explains what each variable means. He or she strives for a program that is comprehensible because its concepts have been introduced in an order that is best for human understanding, using a mixture of formal and informal methods that reinforce each other