Using L&rate Programming to Teach GocNI Programming Praetkes Stephen Shum Computer Science Department Augustana College Sioux Falls, SD 57197 Cllttis Cook Computer Scienee Department Oregon State University Corvallis, OR 97331-32&2 ABSTRACT documentation fails to provide is insight into why a particular program structure is used, or how the program functions. It also The ability to comprehend a program written by other individurds fails to provide information on other relationships between is beeotning increasingly important in sotlsvare development and program components other than these syntactical relationships [4]. maintenanoc. In an attempt to encourage undergraduate Computer Science students to write informative and usable documentation, As eomputcr scienee teachers we have the responsibili~ to teach the literate programming paradigm was incorporated into the students about the importance of informative and usable teaching of one undergraduate Computer Scienee course at documentation as well as readable code. However, students Augustana College, This paper describes the concept of literate usually see documentation and sometimes the design proeeas as programming, the experience of using literate programming to non-essential and extra compared to ooding. They do not sti the teach good programming practices, and the reaulta from the need of documenting a progmm and writing readable code. One experiment that showed that literate programming encourages method we are using to eneourage more readable programs is to more documentation. assign a relatively high percentage of the programming assignment grade to documentation and readability. In fact, the grading INTRODUCTION scheme used by the author at Augustana College in all of his computer scienee courses: 25% each for correctness, design, The ability to comprehend a program written by other individuals readability, and documentation. Such a grsdmg scheme has bczn is becoming increasingly important in software development and found to be quite effeetive in forcing students into the habit of maintenance. Studiex have shown that 30-90% of sofhvare using meaningful names and effective program formatting, expenditure is spent on maintaining existing sotlware [15, 12]. including internal comments, and providing external program Studies have also shown that maintenance programmers spend design documentation in the form of a pseudocode. However, the about half of their time studying the code and related quality of the documentation is far tkom being informative since documentation. This has led Standwh[12] to conclude that the most of the comments are usually mmunenting the obvious. In cost of comprehending a program is the dominant cost of a addition, most students admit that they generate the pseudocode program over its entire life cycle. document from the program code after the program bas been tested. A survey by Chapin[4] of maintainers showed that they pereeived poor documentation as the biggest problem in software Literate programming [7J seemed an ideal solution to the problem maintenance work. Poor documentation has one or more of the of teaching good documentation practices and helping students following characteristics [9, 4, 8] : a. Nonexistent and write informative and usable documentation. Literate incomplete. b. Inconsistency bdxmen code and documentation. c. programming emphasizes writing programs that arc intended to be Difficulty in finding information. d. Not appropriate for all levels read by humans rather than a ecmputer. A literate program is a of programmer experience. single documentation (file) containing both documentation and program. It presents the code and documentation in an There arc a number of CASE tools available that claim to satiso interleaved fashion that matches the programmer’s mental the documentation needs of sotlware maintensnec, These tools representation. Program design, design and code decisions, and generate automatic documentation in the form of reports by static other useful information for the reader arc included in a literate analysis of source code. Examples of documentation produced program. One key feature of literate programming is that the are: control flow &art, data flow chart, cross-reference listings, source code and documentation are created simultaneously. metric reports, all graphs, module biersrehy chart, etc. All of Henec students writing literate programs see the importance of this information is helpful to maintenance programmers to become documentation and clearly see the relation between the dcaign and familiar with the structure of a pmgrsm and to navigate around code. the program during maintenance investigation. What this To test these ideas and the clsii that literate programming Permission to copy without fee all or part of this material is granted provided that the copies ere not mede or distributed for encourages more and better documentation we introduced literate direct commercial advsntaga, the ACM copyright notice end the programming into a junior level computer scienoe programming title of the publication and its date appeer, and notice is given in Spring semester 1992. The AOPS (Abstraction Oriented thet copying Is by permission of the Association for Computing Programming System) literate programming system [11] was Machinery. TO ccpy otherwise, or to republish, requires a fee and/or specifie permission. SIGSCE S4- 3/94, Phceniz Arizcrt@SA @ 1994 ACM &9791 ~..$3.5o 66 used. For an experiment in the class students did two program AOPS (AMraction Oriented Programming System) assignments in AOPS and two in Turbo C, This paper describes the experience+ teaching literate programming and results from Several Web-like literate programming systems have bw+n the experiment. developed since 1984 [1, 5, 6, 10, 13, 14, 15]. However, all of these systems including WEB are programming language ~md LITERATE PROGRAMMING typesetting language dependent, and they do not allow flexible listing and viewing of program code and documentation. Knutb ~ coined the term “literate programming” to emphasize Although AOPS [11] is WEB-like, it is programming language writing code that is intended to be read by humans. He believes and typesetting language independent. Among the other features that the format and structure of a program should be designed to of AOPS arc a flexible lister which allows users to print selected communicate primarily with the humans who read the program portions of the program code and/or documentation and a rather than the computers that execute the program. The hypertext browser which allows users to display relevant presentation of the code should proceed according to the mental information on the screen while suppressing irrelevant details. patterns of the author/programmer rather than the patterns demanded by the language and compiler. He claims that AOPS PROGRAM programming in this way produces better programs with better documentation. An AOPS program is written in levels of abstractions. It conskts of AOPS rules defining the highest level abstraction and all [the The literate programmer writes a source file with the program abstractions used directly and indirectly by the higheat level code and documentation interleaved. The literate paradigm abstraction. A rule consists of an abstraction name, equal sign, recognizes that two different audiences, human readers and type and a body. The abstraction name (hereafter referred to as compilers, will receive the program. For the human readers, AO-name) is a string of characters of any length delimited b!y a there is a iilter program that transforms the source tile program character not used in the AOPS source fde for any other purpose. code and documentation into a form that can be processed by a (We will use the at sign, @, in our examples.) There arc time document formatter. For the computer, there is a filter program basic typea of AOPS rules. that produces a source code program suitable for input to a compiler fiOm the source file. 1. The Code Rule It is important to note that in literate programming program code The program code portion of an AOPS literate program is and documentation are created simultaneously. Lherate constructed from code rules of the form: programming systems contain mechanisms for associating AO-name=code AO-body documentation with sections of code and give the programmer where AO-body consists of legal statements of the underlying freedom to write the program sections in an order that maximizes programming language with embedded AO-names. (Think of an program comprehension. Hence instead of being appended as AO-name embedded in an AO-body of a code rule as a macro extra information to the program, documentation is viewed as an call.) The code rule in essence embodies the goal-plan structure integral pan of the program. Its omission, rather than its of computer programs. The AO-name specifies the goal and the inclusion, is what is most noticeable. AO-body specifies the plan used to achieve the goal. AOIPS provides the ability to explicitly describe this goal-plan structure WEB in a very natural way that is not restricted by the syntax of the programming language, For example, using Pascal as the To promote the literate programming concept, Knutb [m programming language, the code rule for @8qucens program,@ developed the WEB system as art example literate programming is defined as: system. In WEB a programmer writes a source file with the @8queens program@ =code program code and documentation interleaved. WEB has two filter