Documentation standards for beginning students

Abstract

The importance of writing programs that are readable has finally gained preeminence in the struggle with such competing and contradictory goals as “cuteness” and “optimization” of code. As a result, a much greater stress on documentation standards is found in computer science education these days. Industry and government standards for documentation are being more widely adhered to and certain points of agreement have emerged. Some excellent books have been written that cover the subject (Van Tassel, 1974; Ledgard, 1975; Kernighan & Plauger, 1974); however it is safe to say that both the exhaustive treatment of the subject in such publications and the extremely high standards proposed probably preclude wholesale adoption by instructors of beginning level programming courses. What is proposed here is a set of common sense, scaled down documentation standards for the student in a first programming course in, say, FORTRAN, PL/I, ALGOL, or Basic. The following represents an amalgam of documentation requirements achieved as a result of teaching introductory programming to college students for nine years. The actual sources have been the literature, colleagues, and last but not least, experience. They are not intended to represent an “only” or “best” approach; the author has recently encountered other efforts in this direction that must surely be as reasonable and effective. It does represent one educator's approach; it is sufficiently scaled down so that one might reasonably expect to use it as a standard for beginning students; and it may be most useful as a contributor of components to be integrated into a more effective set of standards. The basics of documentation and readable programming include comments, meaningful variable names, labelled output, flowcharts, and clear program flow. The major components of and basic rules for each of these categories will be presented in the context of the needs and limitations of the beginning student.