DesignModules, Headers, CommentsDescribing a Function or MacroDocumentationIndentation ConventionsTestingMechanics and GradingUNIVERSITY OF CALIFORNIADepartment of Electrical Engineeringand Computer SciencesComputer Science DivisionCS61B P. N. HilfingerFall 2001General Guidelines for Programming ProjectsThe programming projects constitute the most important, time-consuming, strenuous,frustrating, and fun part of any programming course. Unfortunately, they are also the mosttime-consuming and difficult coursework to grade. The criteria for a program being good arenot easily defined.Good programs must, of course, work. Even such an obvious statement is not as simpleas it seems. For example, a program that works most of the time can be extremely useful,even though there are some inputs for which it fails. In such cases, it is naturally desirablethat the program detect its failure and avoid disastrous actions, and that the documentationof the program indicate its limitations. A program may work correctly for all legal inputs,but fail on illegal inputs. True, that’s not the program’s fault, but a program designed underthe assumption that input will be perfect reflects rather badly on its implementor’s grasp ofreality.Furthermore, our program descriptions (as in real life) tend to be incomplete or ambiguous.There are some details of a program that are either unimportant to pin down, or that requiresome design to get right. For example, the handling of erroneous or pathological input isgenerally not part of a project description. It is assumed that the programmer will “dosomething reasonable.” So it will be in this course; you will be expected to recognize placeswhere you must fill in details of the design, to fill them in some reasonable fashion, and todocument your decisions, where appropriate.Beyond mere functional correctness, good programming demands some attention to theprocess of programming itself and to stylistic qualities of the program produced. Programstend to last longer than we originally intend. As a result, others (or even we, years later) mustbe able to read, understand, and modify them. Readability in programs, as in books, requiresclear and logical organization and clear, straightforward expression. Errors in well-organizedprograms are easy to find, since it tends to be clear where the error must be.Finally, the current state of the art does not allow us to forgo testing our programs.While testing, in Dijkstra’s oft-quoted phrase, “can show the presence of bugs, but not theirabsence,” it is the usual method of increasing our confidence that our programs, thoughprobably not perfect, are fit for their intended purposes. Too often in programming courses,we spend much too little time on this subject. I venture to guess that most of you havebeen content to run a few examples through your programs—say, the examples given in theproblem description—and then turn them in as quickly as possible, lest continued testing12 P. N. Hilfingeruncover another ten hours’ work. In real life, something more systematic and thorough iscalled for.Programming style often becomes a “religious” issue amongst practitioners. These par-ticular religious beliefs, however, are not among those protected by the Constitution, and Iwill accordingly feel free to lay down some law in the rest of this document.1 DesignIn CS 61B, you will not be called upon to do real program specification from the bottomup, but there will always be minor gaps and ambiguities in the project descriptions, and youwill be expected to resolve them appropriately. Where needed, you will also be expected todocument what you’ve done (see section4).It is difficult to say anything general about what “appropriate resolution” is, but a fewpoints are clear. It is appropriate that programs detect erroneous input; make some attemptat isolating and reporting the problem; and terminate or recover gracefully (i.e., by somemeans that, unlike a segmentation fault or a Java stack dump, gives the impression of beingplanned). It is appropriate that program inputs and outputs be non-cryptic. It is appropri-ate that programs fail gracefully when they run into implementation limits. For example, anappropriate response to running out of memory might be to print a message to that effect,remove temporary files, and terminate cleanly. If your program fails to check for this situa-tion, you will probably end up with an abrupt and enigmatic exception or (in C and C++)segmentation fault.2 Modules, Headers, CommentsI am not a big fan of internal comments, such as this sort of thing.if (qr > z + 1) { // Check for end-of-bufferputs(buf); // ... and start new line if needed.qr = 0;}I would much rather see subprograms (procedures or functions) chosen and named to makethe source code self-documenting:if (endOfBuffer())beginNewLine();Each subprogram, in turn, can have a single comment at the beginning (either just before thesubprogram, or just before the opening ‘{’ of the body) that explains what it does. Indeed, asufficiently small procedure with a self-documenting name may need no comment (for example,endOfBuffer may well not need a comment, but beginNewLine probably does). The test ofideal commenting on subprograms is that a programmer browsing through a particular pieceof code can tell what it does by consulting only the comments and headers of the subprogramsit calls and the comments and declarations of the variables it references.General Guidelines for Programming Projects 3These comments on subprograms should not generally mention just how a subprogramdoes what it does. As the previous discussion suggests, the body of the subprogram shouldsuffice for that. When the subprogram gets too complicated for this to be feasible, it’sprobably time to break it up. Occasionally, the algorithm employed will be sufficiently subtlethat you’ll want to say something about it. In this case, use a separate comment (possibly atthe beginning of the body of the subprogram) to describe the algorithm.All this assumes that you choose reasonable things for subprograms to do. A beginningprogrammer tends to bundle together the strangest sorts of activities into a single subprogram.If you had to write a comment describing one of these, it might read like this./** Outputs characters pos[k] through pos[k+1] of S; increments* count[n] by pos[k+1]-pos[k]; reads the next line into* S, starting at pos[m], unless stopRead is true; and sets* stopRead
View Full Document
Unlocking...