Development and documentation of computer programs in undergraduate computer science programs

Until recently, introductory programming classes in the Department of Computer Science, University of Minnesota, Duluth, concentrated on writing code. Not until the junior or senior year were students required to adhere to basic principles of software engineering. As might be expected, by their junior year students' bad habits, like coding while designing or inserting comments last, were firmly entrenched and difficult, if not impossible, to undo. The solution, it seemed to us, was to prevent bad habits right from the start. Consequently, we developed guidelines for designing and documenting the entire programming effort, from problem statement to post mortem. The guidelines include such steps as: algorithm development in high-level pseudocode with stepwise refinements, structure diagrams with data flow, detailed test descriptions, testing results, and a description of all known bugs. For a given assignment, the instructor chooses the steps to be completed, allowing for flexibility and appropriateness in the design and documentation. Results have been extremely positive. Students start earlier and produce better organized solutions. More students solve the problems correctly. Most importantly, students develop design and documentation skills in the freshman year that carry through and are improved over their four-year stay. Because of this initial success, our department has adopted these guidelines uniformly in all programming classes. In this paper we will describe our guidelines and give some details of their use. We will discuss the philosophy that led us to develop these guidelines and present our observations of their effectiveness.