The main intention behind this approach was to treat a program as literature understandable to human beings. This approach was implemented at Stanford University as a part of research on algorithms and digital typography. Macros in a literate source file are simply title-like or explanatory phrases in a human language that describe human abstractions created while solving the programming problem, and hiding chunks of code or lower-level macros. These macros are similar to the algorithms in pseudocode typically used in teaching computer science. These arbitrary explanatory phrases become precise new operators, created on the fly by the programmer, forming a meta-language on top of the underlying programming language. The preprocessor also provides an ability to write out the content of the macros and to add to already created macros in any place in the text of the literate program source file, thereby disposing of the need to keep in mind the restrictions imposed by traditional programming languages or to interrupt the flow of thought.

Author:Nakora Tugrel
Language:English (Spanish)
Published (Last):19 April 2009
PDF File Size:19.75 Mb
ePub File Size:7.24 Mb
Price:Free* [*Free Regsitration Required]

Leave Feedback Donald Knuth. CSLI, , pg. 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. 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. Ross Williams. FunnelWeb Tutorial Manual, pg 4.

A traditional computer program consists of a text file containing program code. Scattered in amongst the program code are comments which describe the various parts of the code. In literate programming the emphasis is reversed. Instead of writing code containing documentation, the literate programmer writes documentation containing code. No longer does the English commentary injected into a program have to be hidden in comment delimiters at the top of the file, or under procedure headings, or at the end of lines.

Instead, it is wrenched into the daylight and made the main focus. The "program" then becomes primarily a document directed at humans, with the code being herded between "code delimiters" from where it can be extracted and shuffled out sideways to the language system by literate programming tools.

Under the literate programming paradigm, the central activity of programming becomes that of conveying meaning to other intelligent beings rather than merely convincing the computer to behave in a particular way.

It is the difference between performing and exposing a magic trick. Wayne Sewell. Listings generated by the WEB system are unlike any other form of program listings in existence. They resemble programs from computer science textbooks rather than listings from executable programs.

WEB utilizes the TeX document compiler, which includes a typesetting command language capable of tremendous control over document appearance. TeX automatically handles details such as microjustification, kerning, hyphenation, ligatures, and other sophisticated operations, even when the description part of the source is simple ASCII text. WEB adds functions which are specific to computer programs, such as boldface reserved words, italicized identifiers, substitution of true mathematical symbols, and more standard pretty-printer functions such as reformatting and indentation.

The whole concept of code sections, indeed structured programming, is to reduce the amount of text that must be read in order to determine what a piece of code is doing.

The code section is a form of data reduction in that the section name is a placeholder representing the code contained in that section. Anything that is logically part of the section should be moved into it, thereby reducing the complexity of the code where it is referenced. Bart Childs. I use the following list of requirements to imply a definition of a literate program and the minimum set of tools which are needed to prepare, use, and study the resulting code.

The high-level language code and the system documentation of the program come from the same set of source files. The documentation and high-level language code are complementary and should address the same elements of the algorithms being written. The literate program should have logical subdivisions.

Knuth called these modules or sections. The system should be presented in an order based upon logical considerations rather than syntactic constraints.

The documentation should include an examination of alternative solutions and should suggest future maintenance problems and extensions.

The documentation should include a description of the problem and its solution. This should include all aids such as mathematics and graphics that enhance communication of the problem statement and the understanding of its challenge.

Cross references, indices, and different fonts for text, high-level language keywords, variable names, and literals should be reasonably automatic and obvious in the source and the documentation. Modules have three parts: documentation, definitions, and code. At least one of these three parts must be non-null. The documentation portion is often a verbal description of the algorithm.

It may be any textual information that aids the understanding of the problem. These usually describe the problem independent of the chosen language for implementation. It should be an unusual but not exceptional case when a module contains no documentation. Daniel Mall. Literate programming is an excellent method for documenting the internals of software products especially applications with complex features. Literate programming is useful for programs of all sizes. Literate programming encourages meaningful documentation and the inclusion of details that are usually omitted in source code such as the description of algorithms, design decisions, and implementation strategy.

Literate programming increases product quality by requiring software developers to examine and explain their code.

The architecture and design is explained at a conceptual level. Modeling diagrams are included UML. Long procedures are restructuring by folding portions of the code into sections. Innovative ideas, critical technical knowledge, algorithmic solutions, and unusual coding constructions are clearly documented. Literate programs are written to be read by other software developers. Program comprehension is a key activity during corrective and perfective maintenance. High quality documentation facilitates program modification with fewer conceptual errors and resultant defects.

The clarity of literate programs enables team members to reuse existing code and to provide constructive feedback during code reviews. Organization of source code into small sections. The style of literate programming combines source code and documentation into a single source file. Literate programs utilize sections which enable the developer to describe blocks of code in a convenient manner.

Functions are decomposed into several sections. Sections are presented in the order which is best for program comprehension. Code sections improve on verbose commenting by providing the ability to write descriptive paragraphs while avoiding cluttering the source code. Production of a book quality program listing. The typesetting language enables all of the comprehension aids available in books such as pictures, diagrams, figures, tables, formatted equations, bibliographic references, table of contents, and index.

The typographic processing of literate programs produces code listings with elegantly formatted documentation and source code. Listings generated in PDF format include hypertext links. Remember the Basics. There are many factors involved in developing excellent software. Literate programming is just a single technique to be used along with all the other well established software engineering practices.

Here are some software practices related to program documentation: Establish structures, processes, and outcomes see Luke Holman. Generate software requirements and design description see IEEE standards. Practice object oriented design. Choose class names, function names, and variable names wisely. Avoid duplicate code by creating shared functions.

Re-think or refactor code which is difficult to understand. Develop small classes and small functions when feasible. Keep it simple and straight forward as much as possible. Organize large source code files using an outlining editor Leo. Comment source code effectively with header and in-line comments. Document source code using an API documentation standard doxygen. Utilize pre-conditions and post-conditions using assertions. Provide formal or informal proofs of source code correctness.

Conduct peer reviews of deliverables. Implement automated unit testing which is also a form of documentation. Examine source code metrics lines, complexity, etc. Execute static analysis for common coding errors. Donald Knuth. Donald E. He said to me that I should publish my program for TeX. Hoare had heard rumors about my work and he wrote to Stanford suggesting that I keep publication in mind.

I replied to his letter on 16 November much earlier than I remembered. This gave me some experience with writing a program that was fairly easy to read.

Then when I started writing TeX in this period I began the implementation of TeX in October of , and I finished it in May 78 , it was consciously done with structured programming ideas.

Professor Hoare was looking for examples of fairly good-sized programs that people could read. Well, this was frightening.

This was a very scary thing, for a professor of computer science to show someone a large program. At best, a professor might publish very small routines as examples of how to write a program. And we could polish those until


Literate Programming

Leave Feedback Donald Knuth. CSLI, , pg. 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. 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.


Literate programming

Start your review of Literate Programming Write a review Aug 20, Josh Berry rated it it was amazing For the most part, I will assume that folks picking up this book are already predisposed to like the ideas. I will say that it provides a very nice historical context into how software creation has progressed. In particular, the essay on "goto" statements was a lot more fun than would have been expected. The retrospective is fascinating to get an idea of just how Knuth approaches For the most part, I will assume that folks picking up this book are already predisposed to like the ideas.


Oct 3, Literate programming: Knuth is doing it wrong Literate programming advocates this: Order your code for others to read, not for the compiler. Beautifully typeset your code so one can curl up in bed to read it like a novel. Keep documentation in sync with code. I have two beefs with it: the ends are insufficiently ambitious by focusing on a passive representation; and the means were insufficiently polished, by over-emphasizing typesetting at the cost of prose quality. Elaboration, in reverse order: Canonizing typesetting over organization When I look around at the legacy of literate programming, systems to do so-called semi- or quasi-literate programming dominate. These are systems that focus on generating beautifully typeset documentation without allowing the author to arbitrarily order code. But then I went and looked at his literate programs.

Related Articles