Elucidative Programming in Computer Science Education Kurt Nørmark
Thomas Vestdam
Department of Computer Science, Aalborg University Fredrik Bajers Vej 7E, DK-9220 Aalborg, Denmark +45 9635 8896
Department of Computer Science, Aalborg University Fredrik Bajers Vej 7E, DK-9220 Aalborg, Denmark +45 9635 9972
[email protected]
[email protected]
ABSTRACT In this paper we present some ideas and tools for involving real programs in educational contexts. The ideas are based on a paradigm called elucidative programming, which we will motivate and introduce. The tool is the Java Elucidator, with which it is possible to produce a web of Java programs and explanations. We will discuss the usage of the elucidative paradigm both from the teacher’s perspective and the student’s perspective. In the paper we present the results of an experiment with elucidative programming, which involves a group of students. We also report on a recent feature of the Java Elucidator for creation of tutorials. In conclusion, we have found that Elucidative programs can be made attractive elements of a teaching material. In addition, we have found that students can benefit from documenting program understanding explicitly in writing.
Categories and Subject Descriptors D.2.7 [Software Engineering]: Distribution, Maintenance, and Enhancement - Documentation. K.3.2 [Computers and Education]: Computer and Information Science Education – Computer Science education.
General Terms Documentation, Experimentation.
Keywords Elucidative programming
1. INTRODUCTION Elucidative programming [11,10] is a documentation paradigm, which has been proposed as a renewal of the ideas behind literate programming [6]. Literate programming was introduced as a way of explaining programs for humans, in contrast to instructing a machine. One of the main ideas of literate programming is to organize the source program as a number of fragments all of which reside inside the human-oriented explanations. Tools are provided to detach the program from the documentation, and to present the explanations with pieces of programs embedded in the explanations. The basic idea in elucidative programming is to link explanations and program fragments together instead of using physical embedding. An elucidative program is presented and explored in a WEB browser, which exploits the linking in a twoframed setup with mutual navigation between the explanations and relevant fragments of the program. (Figure 1 shows an example, which will be discussed later on in the paper). With this we can associate explanation and documentation without
forcing the programmers to reorganize or re-chunck their programs. Recently, we have refined this support to tutorials, which in some sense brings elucidative programming closer to the starting point of literate programming, without compromising the idea of separate documentation and source programs. In section 2, we will summarize the current status of our work on elucidative programming, including a brief account of two existing elucidative programming tools. Elucidative programming is potentially useful in any context where there is a need to write about a program. Originally, we envisioned elucidative programming to fill a need in the field of software engineering, where thoughts and rationales about a program is easily forgotten, and frequently rediscovered by time consuming work, involving reverse engineering techniques. This branch of our work is still ongoing. In this paper we will focus on educational aspects of elucidative programming. This covers the need of the teacher to explain full and working programs, in order for students to learn from these. As many others, we believe in the power of good examples in the educational process. The other way around, elucidative programming also covers the needs of students to reflect their understanding of programs they have written. Armed with such material, the teacher can more easily focus his or her advice and guidance to the students. In section 3 of this paper we will first discuss elucidative programming as the teacher's means to use real programs of full size in an educational context. This part of the paper is accompanied by an elucidative program example in tutorial style [15]. Following that the student's use of elucidative programming will be discussed.
2. TOOL SUPPORT FOR ELUCIDATIVE PROGRAMMING Two different tools supporting elucidative programming have been build, one for the programming language Scheme, and one for Java. Fundamental for both elucidators is that documentation and program exist as separate entities, and typed links provide navigation between explanations in the documentation and relevant places in the program. The program parts that can be addressed are the abstractions in the program (syntactical elements such as functions, methods, classes, variable etc.) or special comments in the program working as anchors/labels, also called source markers. Both documentation and program are presented as online documents in an ordinary WEB browser. Documentation and program are not in physical proximity as in Literate programming, but the typed links are used to provide navigational proximity between explanations and program fragments [12]. The common elucidative setup is illustrated in
Figure 1. Presentation of an elucidative program in a web-browser.
Figure 1. The top frame contains various navigational features, such as an index of program abstractions and a documentation index. The left frame presents the explanation and the right frame presents program files (i.e. source code). The typed hyperlinks are anchored both at the source end and the destination end, and they can effectively be navigated in both directions. This provides for navigation between a piece of explanation in the left frame and the involved program fragment in the right frame. In addition, navigation is also provided between applied and defining name occurrences in the source program. Both elucidators are supported by Emacs [19,20] at the editor level. The main function of the editor support is to assist the programmer when creating links from the documentation to source code. In order to do this, the elucidator must abstract both source code and documentation. An abstraction gathers information about program abstractions. In the rest of this section, we will present the two tools, focusing on their individual differences and their current status.
2.1 The Scheme Elucidator An elucidative program in the Scheme Elucidator [9,13] is organized as a documentation bundle consisting of a number of programs, a documentation unit and a setup file. A simple markup language is used when writing the documentation, in order to specify structure such as chapters and sections, and in order to specify links to source code. The Scheme Elucidator operates with two link types: weak (blue links) and strong (red links). Weak links are used in documentation that just mentions a program part, whereas strong links are used in documentation that discusses a given program part in detail. In addition, links are provided from standard Scheme functions to explanation in the Scheme language report [4]. The Scheme Elucidator is fully operational, but has not yet been used in software projects outside our research unit.
2.2 The Java Elucidator In the Java Elucidator [12] the documentation bundle contains more than one documentation unit. Each documentation unit is an XML document explaining a specific aspect of the program,
Figure 2. An elucidative program in tutorial style.
and the markup used is essentially very similar to that of the Scheme Elucidator. The presentation of an elucidative program is produced by a webserver utilizing a database containing the information from the last abstraction of the documentation bundle. This setup makes collaborative elucidative programming more attractive. As both documentation and program source code is available as an online resource a group of geographically distributed developers can easily share their collective understanding of the program [12]. In addition, the setup provides context views for all program abstractions (for example, a list of all documentation units linked to a specific program abstraction, or a list of all parts of the source code using specific variable, class, or method). The Java Elucidator is operational, and has been used by both students [21] and people in the industry [1]. The work on the elucidator is ongoing. The future work will involve an improvement of the elucidative program development environment (we expect to integrate the elucidator in the Java Development Environment for Emacs – JDEE [3]).
3. EDUCATIONAL USE OF ELUCIDATIVE PROGRAMMING The educational needs that we discuss in this paper are those of both the teacher and the student. For the teacher's part we primarily consider use of elucidative programming for the
discussion of real programs, which may be both complex and voluminous. But we will also briefly discuss use of elucidative tools for smaller and more traditional program examples in relation to the production of teaching materials. For the student part we consider use of elucidative programming when students work on small assignments, as well as when students work in groups on larger projects (problem-based program development projects). In addition, we also consider elucidative programming, as a means for communication about programs between student and teacher.
3.1 The Teacher’s Perspective The teachers, who want to involve real programs in the educational process, experience the following kinds of problems and challenges: 1.
In-lining of program fragments in explanations versus use of external references. The use of in-lined program fragments in a running text creates a good reading flow at the expense of maintaining the overview of the program. But the sheer volume of a text with in-lining of substantial program fragments hampers the general overview of the exposition. Use of references (links, line numbers, or others) to an external version of the program creates a constant need to follow the references, which disrupts the reading process. As a gain from this approach, the text becomes shorter and more concentrated.
2.
Understanding the wholeness of a program from individual constituents. When a great number of small program fragments are explained and presented it is difficult for the reader to imagine the totality of the aggregated program structures.
3.
Understanding of transverse issues that span a number of abstractions. The explanation of issues with ingredients from several software modules causes particular problems. Chains of messages between several objects, and design patterns that involve several classes can serve as examples of transverse issues.
4.
Maintenance problems of the explanation when the program is updated. If a teaching material is based on real programs, it will sooner or later be necessary to update the programs, on which the material is based. If the binding between the text and the program is very tight (for instance in case large portions of the program is copied and in-lined in the textual material) it will take considerable efforts to revise the teaching material when the program is changed.
As it appears, several of the problems involve trade offs between solutions that affect each other. As such, there is neither miracle medicine nor tools that eliminate them all. As explained in section 2 the Java Elucidator basically takes the stand of using references to entities (classes, methods, variables) in Java source programs from textual explanations, by means of a hypertext linking mechanism. Links are anchored both in the explanations and in the program, facilitating answers to questions like Which program fragments are being discussed? and Which explanations are available on a given variable, method, or class? Taking all problems from above together, we think the solutions provided by the elucidator tools are reasonably, although not perfect. On the positive side •
The program explanation can be rather concentrated because it does not (necessarily) involve in-lining of small or larger program fragments.
•
Transverse relationships can be captured in one or a few sentences, which involve a number of links to the necessary program constituents.
•
The program pieces are presented in their proper context. I.e., variable and methods are always shown in the context of the class, to which they belong.
•
The explanation survives many program updates, although deletions or renaming will cause problems for the references in between the two.
On the other hand - and on the negative side •
The reading process is broken by the necessity of navigating to the program. However, the two-framed layout maintains the context of the explanations when the reader navigates to a program fragment and vice versa.
•
The material is bound to online exposition. This makes it difficult to provide good paper editions of the elucidative
program, in remarkable contrast to literate programs, which is originally designed for the paper medium. As a recent development of the Java Elucidator, and as mentioned earlier, we provide tutorial support which allows us to in-line pieces of programs in the explanations. With this, the Java Elucidator supports both modes of exposition discussed above, at the author’s discretion. As an important observation, the in-lined program fragments are extracted automatically from the source program by the elucidator tool. In other words, we do not end up with two copies of the program - one in the Java source files, and another spread throughout the explanations. In addition, each in-lined program fragment is accompanied by a link to the program in its popper context. We have found that this is a crucial aid for maintaining a holistic understanding of the program. In figure 2 we show a snapshot of an elucidative program that involves tutorial explanation of in-lined program fragments. The boxes in the left frame are extracts of source code (e.g. methods, classes, blocks, or individual code lines). In addition, a link leads the reader to the extract in its proper context, as seen in the right window where the League constructor is shown in the context of the League class. The entire example is available as an electronic WWW resource connected to this paper [15]. The introduction of tutorial support in the Java Elucidator brings us to some extent back to literate programming. We are again dealing with documentation with in-lined program fragments. However, as opposed to literate programming, the program is still a separate entity. As another benefit, we are now closer to printable documentation. As mentioned, it is not easy to produced good papers editions of elucidative programs. It is difficult to replace hyperlinks with good cross-references in a paper version of an elucidative program. However, tutorials are more printer friendly. They mainly consists of source code extracts, hence no cross-referencing is strictly needed. The few remaining hyperlinks can be replaced by simple cross-reference, as their low frequency will not disturb reader friendliness as drastic as in a paper version of a pure elucidative program. Even though tutorials can be used as teaching material, some cutting and pasting is required in order to turn it into lecture slides. We believe that slide presentations of program fragments are a necessary part of CS teaching, and we therefore think that a tighter coupling between teaching material (e.g. lecture slides and lecture notes) and full program examples (including documentation) can be very valuable. We support an integration between the Java Elucidator and the LENO tool (a WEB based lecture note tool [14]), in which the Java Elucidator produces colorized program fragments, ready and easy for LENO to include in a teaching material. In summary, the teacher can use the elucidator to involve full and large-scale programs in the teaching material. The elucidator allows the teacher to balance the trade offs between the wholeness of the program and the wholeness of the explanations. In any case, the Elucidator allows the teacher to adhere to a single sourcing strategy [7] with respect to the involved source programs.
3.2 The Student’s Perspective Computer science students produce programs, for example as assignments in a programming course or as a part of larger projects. At Aalborg University students form groups of 5-7 people [5] for the duration of 4 months in order to produce an academic project that often results in a running piece of software. It is important that students capture their program understanding explicit in writing [17]. The naked source program does not capture and communicate the essential understanding. We have made an experiment at Aalborg University where 7 students used elucidative programming through a 4 months project [21]. We have found that Elucidative programming gives students confidence in their knowledge about the software under development. As the students captured program understanding in writing, the individual student could find support in the documentation when either continuing work started by another student or when dealing with parts of the software written by others. In addition, we found that Elucidative programming is potentially a suitable means for presenting and evaluating software during reviews. If the elucidative program is well structured, a reviewer/teacher can gain a good overview of the software and easily navigate into the details. A well-structured elucidative program typically contains a document giving an overall description of the software. This document is then linked to documents describing the main parts of the system, which in turn are linked to several documents explaining even smaller parts of the software (e.g. classes and complex methods). In addition, links are used to "bind" the documentation together and relate the documentation to actual source code. An elucidative program can be used as a communication medium between a teacher and the students. Literate programming has proven to be a useful paradigm when students wish to (or are instructed to) write about their programs in order to communicate their understanding of problems and solutions [18]. Instead of just being concerned about complying with functional requirements, literate programming leads students into more careful thoughts about code design and code ethics [8]. However, given the experience with more than 25 literate programs (each appr. 20 pages, made by 3-4 students during appr. 45 hours of work, typically using the languageindependent NuWeb system [2]) it has been very difficult to persuade the students to write about the program during the development phase. Similarly, the students were hesitant to chunk their programs into fragments, and to arrange these as part of their report. Almost all of the student groups constructed the programs in the usual fashion, and then they wrote ‘some story about the program’ as a last minute effort. Finally they broke the program into fragments in order to arrange these as part of the documentation (as requested by the teacher). We have come to the conclusion that such usage of literate programming is too problematic in relation to the gains achieved. Use of elucidative programming is more realistic, because it does not call for any splitting of the source program, and neither an organization of these in the proximity of the program explanations. The students can adhere to the necessary principles of physical modularization (such as Java's packages in directories and classes in files) and to the organization supported by integrated development environments. Using elucidative
programming, however, we are still faced with the problems of explaining and writing while programming. We believe that the students - in the ideal situation, and in a good design process should document their understanding during the development process, because it gives better programs [6]. Despite the observations from above, we also realize the value of writing as a reflective afterthought. Sometimes, the students do not understand the solution until the programming is done and the program works. In such situations, it probably only makes little sense to force the students to write about a program prior to its completion. Thus, in such situations we recommend an explorative programming process, and we ask the students to address the important aspects of the program (overview, reflection, rationales) after the programming is completed. In summary, we find that elucidative programming is an attractive alternative to literate programming, seen from a student’s perspective. The Elucidator allows the student to switch back and forth between ‘programming mode’ and ‘explaining mode’ in the development process. Used less ambitious, the Elucidator allows the students to attach a number of reflections to specific program details after the program is written, without affecting or disturbing the source program at all.
4. CONCLUSIONS AND FURTHER WORK We have in this paper explained the use of elucidative programming in an educational context. We have found that elucidative programs can be made attractive elements of a teaching material. Using the Java Elucidator it is possible to write about programs and programming in the context of real programs of full size. The two-framed user interface of the elucidator maintains the reader’s context while navigating to relevant pieces of programs, which in turn are shown in their proper context. The elucidator also allows the teacher to discuss selected program fragments in tutorial style, with in-lining of program excerpts in the explanations. Finally, the elucidator can transfer program fragments to a WEB based presentation tool, ready to be shown with colorized regions for better and easier understanding. As an underlying premise, the program is organized in directories and source files, as requested by the development environment. No source program parts are ever duplicated. We have also found that elucidative programming is a useful tool when it is in the hands of students. Not only do students benefit from documenting program understanding explicitly in writing, but elucidative programming is also a flexible paradigm, as it provides a diversity of ways of attack when students needs to write about their programs.
5. ACKNOWLEDGMENTS The post-graduate students Max R. Andersen, Claus N. Christensen, and Kristian L. Sørensen are acknowledged for the construction of Java Elucidator (version 2) [12]. Their work has been indispensable. All the students at Aalborg University who agreed to use elucidative programming and literate programming in their work and participated in our experiments are gratefully acknowledged for their efforts.
6. REFERENCES [1] Andersen, M. R., and Christensen, C. N. Evaluating Elucidative Programming in an Industrial Setting. Unpublished paper, December 2000. Available via [16].
[2] Briggs, P. Nuweb, A simple literate programming tool. Technical Report, Rice University, Huston, TX, USA, 1993.
[3] Java Development Environment for Emacs (JDEE). http://jde.sunsite.dk/.
[4] Kelsey, R., and Clinger, W., and Rees, J. (editors). Revised report on the algorithmic language Scheme. Higher-Order and Symbolic Computation, 11(1), pp. 7-105, 1998.
[5] Kjersdam, F. and Enemark, S. The Aalborg Experiment -Project Innovation in University Education. Aalborg University Press, Niels Jernesvej, DK-9220 Aalborg, Denmark, 1994.
[6] Knuth, D. E. Literate Programming. The Computer Journal, vol. 27(2), May 1984, pp. 97-111.
[7] Kostur. P. Information Modeling for Single Sourcing. In proceedings of 18th Annual Conference on Computer Documentation - IPCC, SIGDOC 2000, pp. 333-342, 2000 ACM and IEEE.
[8] Leavens G. T., and Baker, A. L., and Honavar V., and LaValle, S. M., and Prabhu, G. Programming is Writing: Why Students Programs need to be Carefully Read. Journal of Mathematics and Computer Education, 32(3), pp. 284295, Fall 1998.
[9] Nørmark, K. An Elucidative Programming Environment for Scheme. In proceedings of NWPER'2000 - Nordic Workshop on Programming Environment Research, pp. 109-126, May 2000. Available via [16].
[10] Nørmark, K. Requirements for an Elucidative Programming Environment. The eighth International Workshop on Program Comprehension, June 2000.
[11] Nørmark, K. Elucidative Programming. Nordic Journal of Computing, vol. 7(2), 2000, pp. 87-105.
[12] Nørmark, K., and Andersen, M. R., and Christensen, C. N. and Sørensen, and Lykkegaard, K., and Staun-Pedersen, S.,
and Kumar, V. Elucidative Programming in Java. In proceedings on the eighteenth annual international conference on Computer documentation (SIGDOC), ACM, September 2000. Available via [16].
[13] Nørmark, K. The elucidative programming home page. http://www.cs.auc.dk/~normark/elucidative-programming/, 1999.
[14] Nørmark, K. WEB Based Lecture Notes – The LENO Approach. 2001 (submitted for publication). Available via http://www.cs.auc.dk/~normark/laml/
[15] Nørmark, K. and Vestdam, T. An elucidative program for “Elucidative Programming in Computer Science Education”. http://www.cs.auc.dk/~odin/api/example/, 2001.
[16] Research programme: Software Quality through Documentation of Program Understanding. http://dopu.cs.auc.dk/, 2000.
[17] Sametinger, J. The Role of Documentation in Programmer Training. Programming Languages: Experiences and Practice, Mark Woodman (Ed.), Chapman & Hall, 1994.
[18] Shum, S., and Cook, C. Using literate programming to teach good programming practices. SIGSE Bulletin: The Papers of the Twenty-Fifth SIGCSE Technical Symposium on Computer Science Education, 26(1), pp.66-70, March 1995.
[19] Stallman, R. GNU Emacs manual. The Free Software Foundation Inc., 1985.
[20] Stallman, R. Emacs: The extensible, customizable, selfdocumenting display editor. In D.R. Barstow, H.E. Shrobe, and E. Sandewall, editors, Interactive Programming Environments, pp. 300-325. McGraw-Hill 1984.
[21] Vestdam, T. Introducing Elucidative Programming in Student Projects. Unpublished paper, January 2001. Available via [16].
