Kevin Karplus
25 May 1994, revised 24 December 1994
Click here if you prefer to see LaTeX (.dvi) output (better for printing).
This essay was prompted by an American Association for Higher Education exercise, which asked for reflections on student work accompanied by examples, but I'm very uncomfortable about copying students' work without their explicit permission. Although I could try to create ``redacted'' copies of student work in which their names do not appear, I would rather reflect on the performance of the class as a whole, and not single out one or two students as exemplars.
There is an inherent bias in this exercise, since the student work is selected by the faculty member. As a dedicated teacher, I'm torn between the desire to analyze the problems encountered by the students who fail the assignment and the need to show myself as a good teacher to my peers, by showing the work of the students who did understand the assignment and succeed at it.
For the essay, I've chosen the in-program documentation exercise form the technical writing course. Of all the assignments in the course, this one is most distinctive of the course and of my teaching-none of the technical writing books talk about this form of writing, yet it is perhaps the most common form of writing for computer engineers.
The structure of the assignment was dictated by the mixed backgrounds of the students. I could not have the students write their own programs and document them, since the level of programming skill and training varies enormously, from people who have over six years of programming experience to students who have just finished their first programming course. To make the students concentrate on the documentation, rather than the programming, I had to give the students the program already written.
Since I was giving the students the program, and just having them change variable names, insert comments, and format the program, I had to find or create a program that was poorly written, but which the students could understand. Wirth's Algorithms + Data Structures = Programs is an excellent source for such material, since Wirth has competent descriptions of his algorithms, but his code is terribly written.
I generally choose a backtracking search algorithm (either Knight's Tour or Eight Queens). These algorithms have the advantage of being fairly simple programs, but requiring recursion. Explaining a recursive algorithm clearly is one of the main points of the assignment, and students generally do well on it if they have understood recursion adequately from previous programming classes. An oft-stated rule of thumb in computer science is that students don't understand recursion and mathematical induction until they have grappled with them at least three times. This assignment, in which they have to explain a recursive algorithm (rather than implementing it or proving something about it), gives them a rather different view of recursion than they have had in other classes.
The approach taken for explaining the recursive routine (using preconditions and postconditions) is a standard one in computer science, but is not often presented as a documentation tool, though I see that as its main use in programming.
The goals for each assignment are explicitly given in the assignments, and so I will just quote the summary here:
In-program documentation is the most common, and most neglected, form of writing for computer programmers. We hope that this exercise teaches you
- what information to put in in-program documentation,
- one way to format the information so that it can be used, and
- the importance of in-program documentation.
The vast majority of the students can do the formatting. They often have strong initial prejudices about formatting, which leads to interesting class discussions about the reasons behind different formatting styles and the importance of a programming group adopting a uniform style.
The students also seem to understand the importance of well-documented code. Anecdotes from the students in the class with industrial experience usually drive home the importance of documentation in memorable ways.
Where the students most often have problems is in determining what needs to be said.
The critical points that I look for in evaluating their work is
whether they explained the meaning of the data structures clearly, and
whether they've explained the recursive routine in terms of what it
accomplishes, rather than what sequence of actions it performs. We
don't do formal pre-condition and post-condition proofs in the
class
, but the students
are exposed to the idea of pre- and post-conditions as an explanatory
tool.
For the Knight's tour, the main data structure is an array holding a partial tour, and the students need to explain what the meaning of a position in the array is, explicitly giving the meaning of a zero entry, which marks unvisited squares. Most of the students who read the assignment manage to get this at least approximately correct.
It is fairly easy to tell who has not read the assignment, since the natural tendency of students is to copy the documentation style of their introductory textbooks, where the programs are documented to point out features of the programming language, rather than to explain the program. As a result, students naturally tend to provide far too many comments in the main body of the code, and not nearly enough for the global variables. The students are clearly warned about this problem in the assignment, and those who make this mistake have almost all admitted to not having read the assignment.
Describing the recursive search is more difficult for the students, as they have primarily had algorithms described to them as sequences of operations. The students either give a description that is correct only for the first call to the procedure (find a tour) or try to explain the sequence of actions the procedure does without explaining what the procedure accomplishes. The students need to find the correct generalization of the procedure description (completing a tour given a partial tour), and correctly describe what happens to the global variables when the search fails (the board contains exactly the partial tour it started from) and when the search succeeds (the board is completely filled in).
The algorithm description assignment has about a page on how to describe a recursive routine, and most years the algorithm description assignment comes before the in-program documentation. In Winter 94, the order of the assignments was changed, but the explanation of recursion was not moved from one assignment to the other. Despite verbal description in class of the way to describe recursion, the performance on the in-program assignment was somewhat poorer with the assignments in the new order. In fact, so few of the students turned in acceptable work, that the entire class was asked to redo the assignment after further in-class discussion (including some exhortation that they actually read the assignment). The redone assignments were somewhat better than normal for the class.
In future, I will either restore the original order of the assignments, or rearrange the text of the assignments to move the explanation about how to describe recursion into the in-program documentation assignment. I have to consult with my co-instructor, to see which of these options she prefers, but I currently lean toward doing the in-program documentation after the algorithm description.